@bluefly/openstandardagents 0.5.0 → 0.5.3

package/examples/agent-skills/SKILLS_CATALOG.md

@@ -1,341 +0,0 @@
-# OSSA Agent Skills Catalog
-
-> **Source**: Based on [Vercel agent-skills](https://agentskills.io/) architecture pattern  
-> **Status**: Active Development  
-> **Version**: 1.0.0  
-> **Platform**: Verify Skills API with `buildkit platform doctor`
-
-## Overview
-
-The OSSA Agent Skills System implements the Vercel agent-skills pattern, enabling context-aware skill discovery and automatic activation. Skills are OSSA agents that specialize in specific domains and auto-activate based on user input, file patterns, frameworks, and project context.
-
-## Architecture
-
-### Separation of Concerns
-
-```
-OSSA Manifest → Agent config, capabilities, tools
-References → Documentation, examples, guidelines  
-Scripts → Automation helpers (optional)
-```
-
-### Skill Structure
-
-Each skill is an OSSA v0.3.5 agent manifest with:
-
-1. **Metadata Labels**: Skill configuration (`skill.priority`, `skill.contexts`, `skill.enabled`)
-2. **Runtime Triggers**: Auto-activation rules (keywords, file patterns, frameworks)
-3. **Capabilities**: Domain-specific tools and expertise
-4. **Extensions**: MoE experts, BAT framework, feedback loops
-
-### Priority-Based Guidance
-
-Skills implement rules ranked by impact:
-
-- **CRITICAL**: Must fix immediately (waterfalls, bundle size)
-- **HIGH**: Significant impact (re-renders, rendering performance)
-- **MEDIUM**: Moderate impact (micro-optimizations, CSS)
-- **LOW**: Edge cases (advanced patterns, micro-benchmarks)
-
-## Integration
-
-### Claude.ai Integration
-
-Skills work seamlessly with Claude.ai:
-
-1. Skills auto-discover from configured paths
-2. Context matching activates relevant skills
-3. Skills provide specialized guidance in conversation
-
-### Cursor Integration
-
-Skills integrate with Cursor IDE:
-
-1. File pattern matching triggers skills on file open/edit
-2. Keyword detection in chat activates skills
-3. Framework detection enables framework-specific skills
-
-### VS Code Extension
-
-Skills can be packaged as VS Code extensions:
-
-1. Register skills via extension manifest
-2. Provide IntelliSense and quick fixes
-3. Show skill recommendations in editor
-
-## Skill Creation Guidelines
-
-### 1. Define Skill Metadata
-
-```yaml
-metadata:
-  name: react-performance-expert
-  labels:
-    skill.priority: 90
-    skill.contexts: development,review
-    skill.enabled: "true"
-    skill.auto_activate: "true"
-```
-
-### 2. Configure Runtime Triggers
-
-```yaml
-runtime:
-  triggers:
-    keywords:
-      - performance
-      - optimize
-      - slow
-    file_patterns:
-      - "**/*.{tsx,jsx}"
-      - "**/components/**"
-    frameworks:
-      - next.js
-      - react
-  activation:
-    automatic: true
-    confidence_threshold: 0.7
-```
-
-### 3. Implement Domain Expertise
-
-```yaml
-role: |
-  You are a React Performance Expert specializing in...
-  
-  CRITICAL Priority Rules:
-  1. Eliminate Waterfalls
-  2. Bundle Optimization
-  ...
-```
-
-### 4. Add Specialized Tools
-
-```yaml
-tools:
-  - name: analyze_bundle
-    description: Analyze bundle size
-    source:
-      type: mcp
-      uri: mcp://build-tools/bundle-analyzer
-```
-
-### 5. Enable v0.3.5 Features
-
-```yaml
-extensions:
-  experts:
-    registry:
-      - id: deep-analysis-expert
-        model: claude-opus-4-5-20251101
-        specializations: [complex_analysis]
-  bat:
-    selection_criteria: [...]
-  feedback:
-    learning:
-      enabled: true
-```
-
-## API Reference
-
-### SkillRegistry Service
-
-```typescript
-import { SkillRegistry } from '@bluefly/openstandardagents/skill-registry';
-
-// Initialize
-await SkillRegistry.initialize([
-  './examples/agent-skills',
-  './examples/ossa-templates',
-]);
-
-// Register skill
-await SkillRegistry.registerFromFile('./skills/my-skill.ossa.yaml');
-
-// Match skills
-const matches = await SkillRegistry.match({
-  userInput: "Optimize my React app",
-  files: ['src/App.tsx'],
-  framework: 'next.js',
-});
-
-// Get skills by context
-const devSkills = SkillRegistry.getByContext('development');
-
-// Enable/disable
-SkillRegistry.enable('react-performance-expert');
-SkillRegistry.disable('react-performance-expert');
-```
-
-### Skill Matching
-
-```typescript
-interface SkillMatchContext {
-  userInput?: string;
-  files?: string[];
-  framework?: string;
-  projectType?: string;
-  keywords?: string[];
-}
-
-interface SkillMatch {
-  skill: SkillMetadata;
-  confidence: number; // 0.0 - 1.0
-  reasons: string[];
-}
-```
-
-## Available Skills
-
-### 1. React Performance Expert
-
-**File**: `examples/ossa-templates/11-react-performance-expert.ossa.yaml`
-
-**Capabilities**:
-- Bundle size optimization
-- Waterfall elimination
-- Re-render optimization
-- Image optimization
-- Code splitting
-
-**Auto-Activation**:
-- Keywords: "performance", "optimize", "slow", "bundle"
-- Files: `**/*.{tsx,jsx}`, `**/components/**`
-- Frameworks: Next.js, React, Remix, Gatsby
-
-**Impact**:
-- 66% latency reduction (waterfall elimination)
-- 200-800ms cold start improvement (barrel imports)
-- 30-50% bundle size reduction (dynamic imports)
-
-### 2. OSSA Agent Authoring
-
-**File**: `examples/agent-skills/ossa-agent-authoring/SKILL.md`
-
-**Capabilities**:
-- Validate OSSA manifests (schema and platform-specific)
-- Scaffold new agent directory and manifest
-- Generate agent-card JSON from manifest
-- Publish path to agentregistry/arctl
-
-**MCP Tools** (when OSSA MCP server is attached): `ossa_validate`, `ossa_scaffold`, `ossa_generate`, `ossa_publish`
-
-**Auto-Activation**:
-- Keywords: "OSSA", "manifest", "agent-card", "scaffold", "validate", "agentregistry"
-- Files: `**/*.ossa.yaml`, `**/manifest.ossa.yaml`, `**/.well-known/agent-card.json`
-
-## Best Practices
-
-### 1. Skill Naming
-
-- Use descriptive names: `react-performance-expert`, `typescript-type-safety-expert`
-- Include domain: `drupal-security-expert`, `api-design-expert`
-- Be specific: `react-performance-expert` not `performance-expert`
-
-### 2. Priority Setting
-
-- **90-100**: Critical, high-impact skills (performance, security)
-- **70-89**: Important skills (type safety, accessibility)
-- **50-69**: Standard skills (code quality, testing)
-- **30-49**: Nice-to-have skills (documentation, formatting)
-- **0-29**: Experimental skills
-
-### 3. Context Selection
-
-- **development**: Active development work
-- **production**: Production deployment checks
-- **review**: Code review assistance
-- **testing**: Test generation and validation
-
-### 4. Trigger Configuration
-
-- **Keywords**: Common terms users might use
-- **File Patterns**: Glob patterns for relevant files
-- **Frameworks**: Framework names (case-insensitive)
-- **Confidence Threshold**: 0.7+ for high-confidence matches
-
-### 5. Tool Design
-
-- Use MCP servers for tool integration
-- Provide clear input/output schemas
-- Include examples in descriptions
-- Support dry-run modes
-
-## Roadmap
-
-### Phase 1: Core Skills (Current)
-
-- ✅ React Performance Expert
-- ✅ OSSA Agent Authoring (MCP: ossa_validate, ossa_scaffold, ossa_generate, ossa_publish)
-- 🔄 TypeScript Type Safety Expert
-- 🔄 Accessibility Champion
-- 🔄 Security Hardening Agent
-
-### Phase 2: Advanced Skills
-
-- 🔄 Database Query Optimizer
-- 🔄 API Design Expert
-- 🔄 Test Coverage Enforcer
-- 🔄 Documentation Generator
-
-### Phase 3: Framework-Specific Skills
-
-- 🔄 Next.js Optimization Expert
-- 🔄 Drupal Best Practices Expert
-- 🔄 Node.js Performance Expert
-- 🔄 Python Code Quality Expert
-
-### Phase 4: Domain-Specific Skills
-
-- 🔄 FinTech Compliance Expert
-- 🔄 Healthcare Data Privacy Expert
-- 🔄 E-commerce Performance Expert
-- 🔄 SaaS Security Expert
-
-## Contributing
-
-### Adding a New Skill
-
-1. Create OSSA manifest in `examples/ossa-templates/`
-2. Follow skill creation guidelines
-3. Add to skills catalog
-4. Write tests for skill registry
-5. Update documentation
-
-### Testing Skills
-
-```typescript
-import { SkillRegistry } from '@bluefly/openstandardagents/skill-registry';
-
-describe('React Performance Expert', () => {
-  it('should match on performance keywords', async () => {
-    const matches = await SkillRegistry.match({
-      userInput: 'My React app is slow',
-    });
-    
-    expect(matches[0].skill.name).toBe('react-performance-expert');
-    expect(matches[0].confidence).toBeGreaterThan(0.7);
-  });
-  
-  it('should match on React files', async () => {
-    const matches = await SkillRegistry.match({
-      files: ['src/components/App.tsx'],
-    });
-    
-    expect(matches.length).toBeGreaterThan(0);
-  });
-});
-```
-
-## References
-
-- [Vercel agent-skills](https://agentskills.io/)
-- [Vercel React Best Practices](https://github.com/vercel-labs/agent-skills/tree/react-best-practices)
-- [OSSA v0.3.5 Specification](../spec/v0.3/)
-- [Skill Registry Service](../../src/services/skill-registry.service.ts)
-
----
-
-**Last Updated**: 2026-01-14  
-**Maintainer**: blueflyio  
-**License**: MIT

package/examples/agent-skills/ossa-agent-authoring/SKILL.md

@@ -1,62 +0,0 @@
----
-name: ossa-agent-authoring
-description: Author and validate OSSA (Open Standard for Software Agents) manifests. Use when creating or editing agent manifests, validating against the OSSA schema, scaffolding new agents, generating agent-card.json, or publishing to a registry. Triggers on tasks involving OSSA YAML/JSON, agent manifests, agent-card, or agentregistry/arctl.
----
-
-# OSSA Agent Authoring
-
-## Overview
-
-Guidelines for authoring and validating OSSA agent manifests. Use the OSSA MCP server tools when available; otherwise use the OSSA CLI.
-
-## When to Apply
-
-- Creating or editing `manifest.ossa.yaml` or OSSA JSON manifests
-- Validating manifests against the OSSA schema
-- Scaffolding a new agent directory and manifest
-- Generating `.well-known/agent-card.json` from a manifest
-- Publishing an OSSA agent to a registry (agentregistry/arctl)
-
-## MCP Tools (OSSA MCP server)
-
-When the OSSA MCP server is attached (e.g. `ossa-mcp` in Cursor/Claude), use:
-
-| Tool | Purpose |
-|------|---------|
-| `ossa_validate` | Validate a manifest file; returns errors and warnings |
-| `ossa_scaffold` | Create a new agent directory and default manifest |
-| `ossa_generate` | Generate agent-card JSON from a manifest |
-| `ossa_publish` | Publish to registry (or get instructions if not configured) |
-
-## CLI Fallback
-
-From the project root or a path with manifests:
-
-```bash
-# Validate
-npx @bluefly/openstandardagents validate <path-to-manifest>
-
-# Scaffold
-npx @bluefly/openstandardagents scaffold [name] -o .agents --with-prompts --with-tools
-
-# Agent card
-npx @bluefly/openstandardagents agent-card <path-to-manifest>
-```
-
-## Manifest Minimum
-
-A valid OSSA v0.4 manifest must have:
-
-- `apiVersion` (e.g. `ossa/v0.4`)
-- `kind: Agent`
-- `metadata.name` (DNS-1123)
-- `spec.role` or `spec.prompts.system.template`
-
-## Governance
-
-- Use schema version matching the manifest `apiVersion` when validating.
-- For platform-specific validation (kagent, langchain, etc.), use the CLI `--platform` flag or the MCP `ossa_validate` platform argument when supported.
-
-## Publish Path
-
-To publish to agentregistry: use `arctl publish` when installed and configured, or POST the manifest and agent-card to the registry API. The `ossa_publish` MCP tool returns next steps when the registry is not configured.

package/examples/agent-skills/react-best-practices/SKILL.md

@@ -1,158 +0,0 @@
----
-name: react-best-practices
-description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
----
-
-# React Best Practices
-
-## Overview
-
-Comprehensive performance optimization guide for React and Next.js applications, containing 40+ rules across 8 categories. Rules are prioritized by impact to guide automated refactoring and code generation.
-
-## When to Apply
-
-Reference these guidelines when:
-- Writing new React components or Next.js pages
-- Implementing data fetching (client or server-side)
-- Reviewing code for performance issues
-- Refactoring existing React/Next.js code
-- Optimizing bundle size or load times
-
-## Priority-Ordered Guidelines
-
-Rules are prioritized by impact:
-
-| Priority | Category | Impact |
-|----------|----------|--------|
-| 1 | Eliminating Waterfalls | CRITICAL |
-| 2 | Bundle Size Optimization | CRITICAL |
-| 3 | Server-Side Performance | HIGH |
-| 4 | Client-Side Data Fetching | MEDIUM-HIGH |
-| 5 | Re-render Optimization | MEDIUM |
-| 6 | Rendering Performance | MEDIUM |
-| 7 | JavaScript Performance | LOW-MEDIUM |
-| 8 | Advanced Patterns | LOW |
-
-## Quick Reference
-
-### Critical Patterns (Apply First)
-
-**Eliminate Waterfalls:**
-- Defer await until needed (move into branches)
-- Use `Promise.all()` for independent async operations
-- Start promises early, await late
-- Use `better-all` for partial dependencies
-- Use Suspense boundaries to stream content
-
-**Reduce Bundle Size:**
-- Avoid barrel file imports (import directly from source)
-- Use `next/dynamic` for heavy components
-- Defer non-critical third-party libraries
-- Preload based on user intent
-
-### High-Impact Server Patterns
-
-- Use `React.cache()` for per-request deduplication
-- Use LRU cache for cross-request caching
-- Minimize serialization at RSC boundaries
-- Parallelize data fetching with component composition
-
-### Medium-Impact Client Patterns
-
-- Use SWR for automatic request deduplication
-- Defer state reads to usage point
-- Use lazy state initialization for expensive values
-- Use derived state subscriptions
-- Apply `startTransition` for non-urgent updates
-
-### Rendering Patterns
-
-- Animate SVG wrappers, not SVG elements directly
-- Use `content-visibility: auto` for long lists
-- Prevent hydration mismatch with inline scripts
-- Use explicit conditional rendering (`? :` not `&&`)
-
-### JavaScript Patterns
-
-- Batch DOM CSS changes via classes
-- Build index maps for repeated lookups
-- Cache repeated function calls
-- Use `toSorted()` instead of `sort()` for immutability
-- Early length check for array comparisons
-
-## References
-
-Full documentation with code examples is available in:
-
-- `references/react-performance-guidelines.md` - Complete guide with all patterns
-- `references/rules/` - Individual rule files organized by category
-
-To look up a specific pattern, grep the rules directory:
-```
-grep -l "suspense" references/rules/
-grep -l "barrel" references/rules/
-grep -l "swr" references/rules/
-```
-
-## Rule Categories in `references/rules/`
-
-- `async-*` - Waterfall elimination patterns
-- `bundle-*` - Bundle size optimization
-- `server-*` - Server-side performance
-- `client-*` - Client-side data fetching
-- `rerender-*` - Re-render optimization
-- `rendering-*` - DOM rendering performance
-- `js-*` - JavaScript micro-optimizations
-- `advanced-*` - Advanced patterns
-
-## OSSA Integration
-
-This skill is available as an OSSA v0.3.5 agent:
-
-- **OSSA Manifest**: `examples/ossa-templates/11-react-performance-expert.ossa.yaml`
-- **Auto-activation**: Keywords, file patterns, frameworks
-- **Tools**: Bundle analyzer, waterfall detector, re-render analyzer
-- **MoE Experts**: Deep analysis, standard analysis, quick scan
-- **BAT Framework**: Technology selection based on complexity
-
-## Usage Examples
-
-### Claude.ai / Cursor
-
-The skill auto-activates when you:
-- Ask about React performance
-- Work with `.tsx` or `.jsx` files
-- Mention "optimize", "slow", "bundle", "waterfall"
-- Use Next.js or React frameworks
-
-### OSSA Agent
-
-```bash
-# Register the skill
-ossa workspace discover
-
-# Use via agent
-ossa run react-performance-expert --analyze src/components/
-```
-
-### Direct Reference
-
-```bash
-# Query specific rules
-grep -r "barrel" examples/agent-skills/react-best-practices/references/
-grep -r "waterfall" examples/agent-skills/react-best-practices/references/
-```
-
-## Quantified Impact
-
-- **Waterfall elimination**: 66% latency reduction
-- **Barrel import fixes**: 200-800ms cold start improvement
-- **Lazy state initialization**: Runs once vs every render
-- **Dynamic imports**: 30-50% bundle size reduction
-- **React.cache**: Eliminates duplicate requests per render
-
----
-
-**Source**: Based on [Vercel agent-skills](https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices)  
-**OSSA Version**: v0.3.5  
-**Last Updated**: 2026-01-14