@bluefly/openstandardagents 0.5.0 → 0.5.3

package/examples/agent-skills/react-best-practices/references/react-performance-guidelines.md

@@ -1,500 +0,0 @@
-# React Best Practices
-
-**Version 0.1.0**  
-Vercel Engineering  
-January 2026
-
-> **Note:**  
-> This document is mainly for agents and LLMs to follow when maintaining,  
-> generating, or refactoring React and Next.js codebases at Vercel. Humans  
-> may also find it useful, but guidance here is optimized for automation  
-> and consistency by AI-assisted workflows.
-
----
-
-## Abstract
-
-Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
-
----
-
-## Table of Contents
-
-1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
-   - 1.1 [Defer Await Until Needed](#11)
-   - 1.2 [Dependency-Based Parallelization](#12)
-   - 1.3 [Prevent Waterfall Chains in API Routes](#13)
-   - 1.4 [Promise.all() for Independent Operations](#14)
-   - 1.5 [Strategic Suspense Boundaries](#15)
-2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
-   - 2.1 [Avoid Barrel File Imports](#21)
-   - 2.2 [Conditional Module Loading](#22)
-   - 2.3 [Defer Non-Critical Third-Party Libraries](#23)
-   - 2.4 [Dynamic Imports for Heavy Components](#24)
-   - 2.5 [Preload Based on User Intent](#25)
-3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
-   - 3.1 [Cross-Request LRU Caching](#31)
-   - 3.2 [Minimize Serialization at RSC Boundaries](#32)
-   - 3.3 [Parallel Data Fetching with Component Composition](#33)
-   - 3.4 [Per-Request Deduplication with React.cache()](#34)
-4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**
-   - 4.1 [Deduplicate Global Event Listeners](#41)
-   - 4.2 [Use SWR for Automatic Deduplication](#42)
-5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**
-   - 5.1 [Defer State Reads to Usage Point](#51)
-   - 5.2 [Extract to Memoized Components](#52)
-   - 5.3 [Narrow Effect Dependencies](#53)
-   - 5.4 [Subscribe to Derived State](#54)
-   - 5.5 [Use Lazy State Initialization](#55)
-   - 5.6 [Use Transitions for Non-Urgent Updates](#56)
-6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**
-   - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61)
-   - 6.2 [CSS content-visibility for Long Lists](#62)
-   - 6.3 [Hoist Static JSX Elements](#63)
-   - 6.4 [Optimize SVG Precision](#64)
-   - 6.5 [Prevent Hydration Mismatch Without Flickering](#65)
-   - 6.6 [Use Activity Component for Show/Hide](#66)
-   - 6.7 [Use Explicit Conditional Rendering](#67)
-7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**
-   - 7.1 [Batch DOM CSS Changes](#71)
-   - 7.2 [Build Index Maps for Repeated Lookups](#72)
-   - 7.3 [Cache Property Access in Loops](#73)
-   - 7.4 [Cache Repeated Function Calls](#74)
-   - 7.5 [Cache Storage API Calls](#75)
-   - 7.6 [Combine Multiple Array Iterations](#76)
-   - 7.7 [Early Length Check for Array Comparisons](#77)
-   - 7.8 [Early Return from Functions](#78)
-   - 7.9 [Hoist RegExp Creation](#79)
-   - 7.10 [Use Loop for Min/Max Instead of Sort](#710)
-   - 7.11 [Use Set/Map for O(1) Lookups](#711)
-   - 7.12 [Use toSorted() Instead of sort() for Immutability](#712)
-8. [Advanced Patterns](#8-advanced-patterns) — **LOW**
-   - 8.1 [Store Event Handlers in Refs](#81)
-   - 8.2 [useLatest for Stable Callback Refs](#82)
-
----
-
-## 1. Eliminating Waterfalls
-
-**Impact: CRITICAL**
-
-Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
-
-### 1.1 Defer Await Until Needed
-
-Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
-
-**Incorrect: blocks both branches**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
-  const userData = await fetchUserData(userId)
-  
-  if (skipProcessing) {
-    // Returns immediately but still waited for userData
-    return { skipped: true }
-  }
-  
-  // Only this branch uses userData
-  return processUserData(userData)
-}
-```
-
-**Correct: only blocks when needed**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
-  if (skipProcessing) {
-    // Returns immediately without waiting
-    return { skipped: true }
-  }
-  
-  // Fetch only when needed
-  const userData = await fetchUserData(userId)
-  return processUserData(userData)
-}
-```
-
-**Another example: early return optimization**
-
-```typescript
-// Incorrect: always fetches permissions
-async function updateResource(resourceId: string, userId: string) {
-  const permissions = await fetchPermissions(userId)
-  const resource = await getResource(resourceId)
-  
-  if (!resource) {
-    return { error: 'Not found' }
-  }
-  
-  if (!permissions.canEdit) {
-    return { error: 'Forbidden' }
-  }
-  
-  return await updateResourceData(resource, permissions)
-}
-
-// Correct: fetches only when needed
-async function updateResource(resourceId: string, userId: string) {
-  const resource = await getResource(resourceId)
-  
-  if (!resource) {
-    return { error: 'Not found' }
-  }
-  
-  const permissions = await fetchPermissions(userId)
-  
-  if (!permissions.canEdit) {
-    return { error: 'Forbidden' }
-  }
-  
-  return await updateResourceData(resource, permissions)
-}
-```
-
-This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
-
-### 1.2 Dependency-Based Parallelization
-
-For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
-
-**Incorrect: profile waits for config unnecessarily**
-
-```typescript
-const [user, config] = await Promise.all([
-  fetchUser(),
-  fetchConfig()
-])
-const profile = await fetchProfile(user.id)
-```
-
-**Correct: config and profile run in parallel**
-
-```typescript
-import { all } from 'better-all'
-
-const { user, config, profile } = await all({
-  async user() { return fetchUser() },
-  async config() { return fetchConfig() },
-  async profile() {
-    return fetchProfile((await this.$.user).id)
-  }
-})
-```
-
-Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
-
-### 1.3 Prevent Waterfall Chains in API Routes
-
-In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
-
-**Incorrect: config waits for auth, data waits for both**
-
-```typescript
-export async function GET(request: Request) {
-  const session = await auth()
-  const config = await fetchConfig()
-  const data = await fetchData(session.user.id)
-  return Response.json({ data, config })
-}
-```
-
-**Correct: auth and config start immediately**
-
-```typescript
-export async function GET(request: Request) {
-  const sessionPromise = auth()
-  const configPromise = fetchConfig()
-  const session = await sessionPromise
-  const [config, data] = await Promise.all([
-    configPromise,
-    fetchData(session.user.id)
-  ])
-  return Response.json({ data, config })
-}
-```
-
-For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
-
-### 1.4 Promise.all() for Independent Operations
-
-When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
-
-**Incorrect: sequential execution, 3 round trips**
-
-```typescript
-const user = await fetchUser()
-const posts = await fetchPosts()
-const comments = await fetchComments()
-```
-
-**Correct: parallel execution, 1 round trip**
-
-```typescript
-const [user, posts, comments] = await Promise.all([
-  fetchUser(),
-  fetchPosts(),
-  fetchComments()
-])
-```
-
-### 1.5 Strategic Suspense Boundaries
-
-Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
-
-**Incorrect: wrapper blocked by data fetching**
-
-```tsx
-async function Page() {
-  const data = await fetchData() // Blocks entire page
-  
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <div>
-        <DataDisplay data={data} />
-      </div>
-      <div>Footer</div>
-    </div>
-  )
-}
-```
-
-The entire layout waits for data even though only the middle section needs it.
-
-**Correct: wrapper shows immediately, data streams in**
-
-```tsx
-function Page() {
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <div>
-        <Suspense fallback={<Skeleton />}>
-          <DataDisplay />
-        </Suspense>
-      </div>
-      <div>Footer</div>
-    </div>
-  )
-}
-
-async function DataDisplay() {
-  const data = await fetchData() // Only blocks this component
-  return <div>{data.content}</div>
-}
-```
-
-Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
-
-**When NOT to use this pattern:**
-
-```tsx
-
-```
-
-**When NOT to use this pattern:**
-
-```tsx
-
-```
-
----
-
-## 2. Bundle Size Optimization
-
-**Impact: CRITICAL**
-
-Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
-
-### 2.1 Avoid Barrel File Imports
-
-Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
-
-Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
-
-**Incorrect: imports entire library**
-
-```tsx
-import { Check, X, Menu } from 'lucide-react'
-// Loads 1,583 modules, takes ~2.8s extra in dev
-// Runtime cost: 200-800ms on every cold start
-
-import { Button, TextField } from '@mui/material'
-// Loads 2,225 modules, takes ~4.2s extra in dev
-```
-
-**Correct: imports only what you need**
-
-```tsx
-import Check from 'lucide-react/dist/esm/icons/check'
-import X from 'lucide-react/dist/esm/icons/x'
-import Menu from 'lucide-react/dist/esm/icons/menu'
-// Loads only 3 modules (~2KB vs ~1MB)
-
-import Button from '@mui/material/Button'
-import TextField from '@mui/material/TextField'
-// Loads only what you use
-```
-
-**Alternative: Next.js 13.5+**
-
-```js
-// next.config.js - use optimizePackageImports
-module.exports = {
-  experimental: {
-    optimizePackageImports: ['lucide-react', '@mui/material']
-  }
-}
-
-// Then you can keep the ergonomic barrel imports:
-import { Check, X, Menu } from 'lucide-react'
-// Automatically transformed to direct imports at build time
-```
-
-Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
-
-Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
-
-Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
-
-### 2.2 Conditional Module Loading
-
-Load large data or modules only when a feature is activated.
-
-**Example: lazy-load animation frames**
-
-```tsx
-function AnimationPlayer({ enabled }: { enabled: boolean }) {
-  const [frames, setFrames] = useState<Frame[] | null>(null)
-
-  useEffect(() => {
-    if (enabled && !frames && typeof window !== 'undefined') {
-      import('./animation-frames.js')
-        .then(mod => setFrames(mod.frames))
-        .catch(() => setEnabled(false))
-    }
-  }, [enabled, frames])
-
-  if (!frames) return <Skeleton />
-  return <Canvas frames={frames} />
-}
-```
-
-The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
-
-### 2.3 Defer Non-Critical Third-Party Libraries
-
-Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
-
-**Incorrect: blocks initial bundle**
-
-```tsx
-import { Analytics } from '@vercel/analytics/react'
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        {children}
-        <Analytics />
-      </body>
-    </html>
-  )
-}
-```
-
-**Correct: loads after hydration**
-
-```tsx
-import dynamic from 'next/dynamic'
-
-const Analytics = dynamic(
-  () => import('@vercel/analytics/react').then(m => m.Analytics),
-  { ssr: false }
-)
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        {children}
-        <Analytics />
-      </body>
-    </html>
-  )
-}
-```
-
-### 2.4 Dynamic Imports for Heavy Components
-
-Use `next/dynamic` to lazy-load large components not needed on initial render.
-
-**Incorrect: Monaco bundles with main chunk ~300KB**
-
-```tsx
-import { MonacoEditor } from './monaco-editor'
-
-function CodePanel({ code }: { code: string }) {
-  return <MonacoEditor value={code} />
-}
-```
-
-**Correct: Monaco loads on demand**
-
-```tsx
-import dynamic from 'next/dynamic'
-
-const MonacoEditor = dynamic(
-  () => import('./monaco-editor').then(m => m.MonacoEditor),
-  { ssr: false }
-)
-
-function CodePanel({ code }: { code: string }) {
-  return <MonacoEditor value={code} />
-}
-```
-
-### 2.5 Preload Based on User Intent
-
-Preload heavy bundles before they're needed to reduce perceived latency.
-
-**Example: preload on hover/focus**
-
-```tsx
-function EditorButton({ onClick }: { onClick: () => void }) {
-  const preload = () => {
-    if (typeof window !== 'undefined') {
-      void import('./monaco-editor')
-    }
-  }
-
-  return (
-    <button
-      onMouseEnter={preload}
-      onFocus={preload}
-      onClick={onClick}
-    >
-      Open Editor
-    </button>
-  )
-}
-```
-
-**Example: preload when feature flag is enabled**
-
-```tsx
-function FlagsProvider({ children, flags }: Props) {
-  useEffect(() => {
-    if (flags.editorEnabled && typeof window !== 'undefined') {
-      void import('./monaco-editor').then(mod => mod.init())
-    }
-  }, [flags.editorEnabled])
-
-  return <FlagsContext.Provider value={flags}>
-    {children}
-  </FlagsContext.Provider>
-}
-```

package/examples/agent-taxonomy-example.ossa.yaml

@@ -1,89 +0,0 @@
-apiVersion: ossa/v0.4.7
-kind: Agent
-metadata:
-  name: customer-service-orchestrator
-  version: 1.0.0
-  description: Multi-agent orchestrator for customer service workflows
-
-  # NEW in v0.4.4: Agent Taxonomy
-  agentType: claude                    # Runtime platform (claude, kagent, openai, etc.)
-  agentKind: orchestrator              # Functional role (what it does)
-
-  agentArchitecture:
-    pattern: swarm                     # Architecture pattern
-    capabilities:
-      - handoff                        # Can transfer to other agents
-      - streaming                      # Supports streaming responses
-      - context                        # Maintains conversation context
-      - tools                          # Can call external tools
-      - vision                         # Can process images
-
-    coordination:
-      handoffStrategy: automatic       # How agents coordinate
-      maxDepth: 5                      # Max orchestration depth
-
-    runtime:
-      scalability: horizontal          # Can scale horizontally
-      executionModel: streaming        # Streaming execution model
-      preferredRegion: us-east-1       # Preferred deployment region
-
-  labels:
-    domain: customer-service
-    team: support-engineering
-    environment: production
-
-spec:
-  model:
-    provider: anthropic
-    name: claude-sonnet-4-5-20250929
-    temperature: 0.7
-    max_tokens: 4096
-
-  system: |
-    You are an intelligent customer service orchestrator.
-    Route customer requests to appropriate specialist agents:
-    - sales-agent: For pricing and purchasing questions
-    - support-agent: For technical support issues
-    - billing-agent: For billing and payment questions
-
-  tools:
-    - name: transfer_to_sales
-      description: Transfer to sales specialist
-      input_schema:
-        type: object
-        properties:
-          reason:
-            type: string
-            description: Reason for transfer
-        required: [reason]
-
-    - name: transfer_to_support
-      description: Transfer to technical support
-      input_schema:
-        type: object
-        properties:
-          issue_type:
-            type: string
-            enum: [bug, feature, question]
-        required: [issue_type]
-
-    - name: transfer_to_billing
-      description: Transfer to billing specialist
-      input_schema:
-        type: object
-        properties:
-          billing_issue:
-            type: string
-        required: [billing_issue]
-
-  context:
-    session_timeout: 30m
-    max_turns: 20
-
-  handoffs:
-    - to: sales-agent
-      condition: "user asks about pricing or purchasing"
-    - to: support-agent
-      condition: "user has technical issues"
-    - to: billing-agent
-      condition: "user has billing questions"

package/examples/agents/01-customer-support-bot/.env.example

@@ -1,32 +0,0 @@
-# OpenAI Configuration
-OPENAI_API_KEY=sk-...
-
-# Redis Configuration
-REDIS_URL=redis://localhost:6379
-
-# Server Configuration
-PORT=8080
-NODE_ENV=development
-
-# Logging
-LOG_LEVEL=info
-
-# Metrics
-METRICS_ENABLED=true
-METRICS_PORT=9090
-
-# Observability
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-TRACING_ENABLED=true
-
-# Rate Limiting
-RATE_LIMIT_MAX=100
-RATE_LIMIT_WINDOW_MS=60000
-
-# Security
-ENABLE_PII_REDACTION=true
-ENABLE_INPUT_VALIDATION=true
-
-# Feature Flags
-ENABLE_TICKET_CREATION=true
-ENABLE_EMAIL_SENDING=true

package/examples/agents/01-customer-support-bot/Dockerfile

@@ -1,30 +0,0 @@
-FROM node:18-alpine AS base
-
-# Install Python for LangChain
-RUN apk add --no-cache python3 py3-pip
-
-WORKDIR /app
-
-# Copy package files
-COPY package*.json ./
-COPY requirements.txt ./
-
-# Install dependencies
-RUN npm ci --only=production
-RUN pip3 install --no-cache-dir -r requirements.txt
-
-# Copy application
-COPY . .
-
-# Build TypeScript
-RUN npm run build
-
-# Expose port
-EXPOSE 8080
-
-# Health check
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-  CMD node healthcheck.js || exit 1
-
-# Run application
-CMD ["node", "dist/index.js"]