opencode-skills-collection 1.0.186 → 1.0.187

package/bundled-skills/faf-expert/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: faf-expert
+description: "Advanced .faf (Foundational AI-context Format) specialist. IANA-registered format, MCP server config, championship scoring, bi-directional sync."
+category: coding
+risk: safe
+source: community
+source_repo: Wolfe-Jam/faf-skills
+source_type: community
+date_added: "2026-04-07"
+author: wolfejam
+tags: [faf, ai-context, project-management, mcp, iana]
+tools: [claude, cursor, gemini, windsurf]
+---
+
+# FAF Expert - Advanced AI Context Architecture
+
+**Master the IANA-registered format that makes AI understand your projects.**
+
+Transform any codebase into an AI-intelligent project with persistent context that survives across sessions, tools, and AI platforms. Expert-level control over the foundational layer that powers modern AI development workflows.
+
+## When to Use This Skill
+
+Use FAF Expert when you need:
+
+| Scenario | What FAF Expert Provides |
+|----------|---------------------------|
+| **Complex project setup** | Expert configuration of .faf files and MCP servers |
+| **Championship scoring** | Achieve 85%+ AI-readiness scores for production projects |
+| **Multi-AI workflows** | Universal context that works across Claude, Cursor, Gemini, Windsurf |
+| **Legacy codebase revival** | Transform archaeology into AI-readable project DNA |
+| **Team collaboration** | Standardized context format for consistent AI assistance |
+| **Enterprise deployment** | Professional MCP server configuration and management |
+
+## Real-World Examples
+
+### Example 1: Legacy Enterprise Java System
+```yaml
+# Achieved: 92% Gold tier with FAF Expert
+project:
+  name: enterprise-payment-api
+  goal: Mission-critical payment processing system
+  
+stack:
+  backend: java-spring
+  database: oracle
+  runtime: java-11
+  deployment: kubernetes
+  
+human_context:
+  where: AWS EKS production cluster
+  when: Legacy system from 2018, modernizing 2026
+  how: Spring Boot 2.7, Oracle 19c, Docker containerization
+```
+
+### Example 2: Modern React Dashboard
+```yaml
+# Achieved: 97% Gold tier performance
+project:
+  name: analytics-dashboard
+  goal: Real-time analytics for SaaS platform
+  
+stack:
+  frontend: react-18
+  css_framework: tailwind
+  state: zustand
+  build: vite
+  testing: vitest
+  deployment: vercel
+```
+
+## Core Capabilities
+
+### 🏆 Championship Scoring System
+- **Gold Tier (95%+)**: Production-ready AI context
+- **Silver Tier (85%+)**: Professional development standard  
+- **Bronze Tier (70%+)**: Solid foundation for AI assistance
+
+### 🔧 MCP Server Configuration
+Expert setup of claude-faf-mcp with 33 tools:
+```json
+{
+  "mcpServers": {
+    "faf": {
+      "command": "npx",
+      "args": ["-y", "claude-faf-mcp@latest"]
+    }
+  }
+}
+```
+
+### 🔄 Bi-Directional Sync
+Keep context synchronized across platforms:
+- `.faf` ↔ `CLAUDE.md` 
+- `.faf` ↔ `.cursorrules`
+- `.faf` ↔ `GEMINI.md`
+- `.faf` ↔ `AGENTS.md`
+
+### 📊 Mk4 Architecture Framework
+33-slot IANA format for comprehensive project context:
+- Project identity and goals
+- Technical stack detection  
+- Human context (who/what/why/where/when/how)
+- Architecture patterns
+- Deployment configuration
+
+## Getting Started
+
+### Quick Installation
+```bash
+# Install FAF CLI
+npm install -g faf-cli
+
+# Initialize your project
+faf init
+
+# Score AI-readiness
+faf score --details
+
+# Set up MCP server
+faf mcp install
+```
+
+### Expert Commands
+```bash
+# Advanced scoring with breakdown
+faf score --championship --verbose
+
+# Multi-platform sync
+faf bi-sync --target all
+
+# Validate format compliance
+faf validate --strict
+
+# Enhanced AI optimization
+faf enhance --model claude --focus completeness
+```
+
+## Success Metrics
+
+**Real Performance Data:**
+- **52k+ downloads** across FAF ecosystem
+- **800+ comprehensive tests** (CLI + MCP)
+- **IANA-registered format** (application/vnd.faf+yaml)
+- **153+ validated formats** supported
+- **Championship-grade performance** (<50ms execution)
+
+## Platform Compatibility
+
+### Supported AI Tools
+- ✅ **Claude Code** - Native MCP integration
+- ✅ **Cursor** - .cursorrules sync
+- ✅ **Gemini CLI** - GEMINI.md sync  
+- ✅ **Windsurf** - .windsurfrules support
+- ✅ **Universal** - Works with any AI that reads YAML
+
+### MCP Servers Available
+- `claude-faf-mcp` - 33 tools, 391 tests
+- `grok-faf-mcp` - xAI/Grok optimized
+- `rust-faf-mcp` - Native performance (4.3MB binary)
+- `gemini-faf-mcp` - Google Gemini integration
+
+## Advanced Patterns
+
+### Enterprise Configuration
+```yaml
+faf_version: "3.0"
+project:
+  name: enterprise-platform
+  tier: production
+  
+human_context:
+  team_size: 50+
+  compliance: SOC2, HIPAA
+  deployment: multi-region
+  
+stack:
+  architecture: microservices
+  orchestration: kubernetes
+  monitoring: datadog
+  security: vault
+```
+
+### Legacy System Revival
+```yaml
+# Transform 10-year-old codebase to AI-ready
+project:
+  archaeology: true
+  modernization_target: 2026
+  
+stack:
+  legacy: php-5.6
+  migration_path: laravel-11
+  database_upgrade: mysql-8
+```
+
+## Expert Resources
+
+- **Documentation**: https://faf.one
+- **MCP Registry**: Official Anthropic steward
+- **CLI Reference**: `faf --help`
+- **Community**: Discord server with 1000+ developers
+- **Enterprise**: Professional support available
+
+## When to Use faf-wizard Instead
+
+Use `faf-wizard` for:
+- ✅ Quick project setup
+- ✅ One-click generation
+- ✅ Beginner-friendly workflow
+- ✅ Automated stack detection
+
+Use `faf-expert` for:
+- 🎯 Fine-tuned configuration
+- 🎯 Championship scoring optimization
+- 🎯 Multi-platform sync management
+- 🎯 Enterprise deployment patterns
+- 🎯 Advanced MCP server setup
+
+---
+
+*Master the format that makes AI understand your projects. FAF Expert - for when you need championship-grade AI context architecture.*

package/bundled-skills/faf-wizard/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: faf-wizard
+description: "Done-for-you .faf generator. One-click AI context for any project - new, legacy, or famous. Auto-detects stack, scores readiness, works everywhere."
+category: productivity
+risk: safe
+source: community
+source_repo: Wolfe-Jam/faf-skills
+source_type: community
+date_added: "2026-04-07"
+author: wolfejam
+tags: [faf, automation, project-setup, ai-context, productivity]
+tools: [claude, cursor, gemini, windsurf, any-ai]
+---
+
+# FAF Wizard - One-Click AI Intelligence
+
+**The pit crew for your projects.** Point it at any codebase and get scored, AI-ready context in 60 seconds.
+
+Transform any project - new, legacy, famous OSS, or forgotten side projects - into an AI-intelligent workspace with persistent context that works across all AI tools.
+
+## The Problem It Solves
+
+**Even React.js scores 0% AI-readiness.** Famous repositories have no AI context.
+
+| What Exists | What It Tells AI |
+|-------------|------------------|
+| README.md | "What this does" (for humans) |
+| docs/ | "How to use it" (for humans) |
+| **project.faf** | "How to help build this" (for AI) |
+
+Documentation tells humans how to use your code. AI context tells AI how to help you build it. **They're completely different things.**
+
+## Works on ANY Project
+
+| Project Type | What FAF Wizard Does |
+|-------------|----------------------|
+| **Brand new** | Perfect AI context from line one |
+| **Legacy nightmare** | AI finally understands the archaeology |
+| **Famous OSS** | Even React doesn't have this |
+| **Side projects** | Stop re-explaining every session |
+| **Client handoffs** | Portable context for any AI tool |
+| **Team projects** | Shared context that everyone can use |
+
+## Real Success Stories
+
+### Before/After: Legacy E-commerce Platform
+```
+Before: "This 50k-line PHP codebase from 2015..."
+AI: "I don't understand this architecture"
+
+After: 60 seconds with FAF Wizard
+AI: "I see this is a Laravel-based e-commerce system with 
+payment processing, inventory management, and multi-tenant 
+architecture. Here's how I can help..."
+```
+
+### Before/After: Modern React App
+```
+Before: Every AI session starts with context explanation
+Time lost: 5-10 minutes per session
+
+After: project.faf exists
+AI: Instant understanding, productive from message one
+Time saved: 2+ hours per day
+```
+
+## The 60-Second Workflow
+
+### Step 1: Detection (10 seconds)
+```bash
+faf auto
+# Scans manifest files, directory structure, dependencies
+# Detects: React + TypeScript + Tailwind + Vercel
+```
+
+### Step 2: Generation (30 seconds)  
+```yaml
+# Auto-generated project.faf
+project:
+  name: my-saas-dashboard  
+  goal: Customer analytics platform
+
+stack:
+  frontend: react-18
+  css: tailwind
+  deployment: vercel
+  
+human_context:
+  who: Solo founder
+  what: SaaS analytics dashboard
+  why: Customer insights for small businesses
+```
+
+### Step 3: Scoring & Report (20 seconds)
+```
+✅ Generated: project.faf
+🏆 AI-Readiness: 87% Bronze - Production ready
+
+Filled: 9/11 active slots
+Ignored: 22 slots (not applicable)
+
+To reach Silver (95%):
+  + Add API documentation (+5%)  
+  + Define deployment details (+3%)
+```
+
+## Performance Data (Real Numbers)
+
+**Analyzed 8,400+ Projects:**
+- ✅ **99.2% detection accuracy** across 153+ formats
+- ✅ **Average generation time**: 12.3 seconds
+- ✅ **Bronze tier or higher**: 94% of projects
+- ✅ **Zero manual configuration**: Works out of the box
+
+### Format Support
+Automatically detects and configures:
+- **JavaScript**: React, Vue, Angular, Svelte, Next.js, Nuxt
+- **Python**: Django, Flask, FastAPI, Jupyter, Poetry
+- **TypeScript**: All JS frameworks + native TS projects  
+- **Rust**: Cargo projects, CLI tools, web servers
+- **Go**: Modules, Docker, microservices
+- **Java**: Maven, Gradle, Spring Boot
+- **+147 more formats**
+
+## Universal Compatibility
+
+### Works With Every AI Tool
+- ✅ **Claude Code** - Reads .faf natively
+- ✅ **Cursor** - Auto-syncs to .cursorrules  
+- ✅ **Gemini CLI** - Converts to GEMINI.md
+- ✅ **Windsurf** - Syncs to .windsurfrules
+- ✅ **ChatGPT** - Readable YAML format
+- ✅ **Any AI** - Universal format support
+
+### Migration Support
+Already have AI context files?
+```bash
+# Migrates existing context
+faf migrate --from .cursorrules
+faf migrate --from CLAUDE.md  
+faf migrate --from README.md
+
+# One format, works everywhere
+faf sync --target all
+```
+
+## Installation Options
+
+### Option 1: CLI (Recommended)
+```bash
+npm install -g faf-cli
+cd your-project
+faf auto
+```
+
+### Option 2: MCP Server (Claude Code)
+```json
+{
+  "mcpServers": {
+    "faf": {
+      "command": "npx", 
+      "args": ["-y", "claude-faf-mcp@latest"]
+    }
+  }
+}
+```
+
+### Option 3: Browser Extension
+Install from Chrome Web Store - works on any Git repository.
+
+## Three-Phase Intelligence
+
+### Phase 1: Stack Detection
+- Scans `package.json`, `Cargo.toml`, `pyproject.toml`, etc.
+- Analyzes directory structure and file patterns
+- Identifies frameworks, deployment targets, testing setup
+
+### Phase 2: Context Mining  
+- Extracts project description from README
+- Identifies architecture patterns from code structure
+- Pulls dependency information for AI context
+
+### Phase 3: Optimization
+- Generates focused 33-slot IANA format
+- Validates against format specification
+- Scores AI-readiness with improvement suggestions
+
+## Success Metrics by Project Type
+
+| Project Type | Avg Score | Time to Bronze | Detection Rate |
+|-------------|-----------|----------------|----------------|
+| **React/Vue** | 89% | Instant | 99.8% |
+| **Python Django** | 91% | Instant | 99.5% |  
+| **Rust CLI** | 85% | Instant | 99.1% |
+| **Legacy PHP** | 76% | 30 seconds | 94.2% |
+| **Monorepo** | 82% | 45 seconds | 91.8% |
+
+## When to Use faf-expert Instead
+
+Use `faf-wizard` for:
+- ✅ Quick project onboarding
+- ✅ Automatic everything
+- ✅ "Just make it work"
+- ✅ Time-constrained scenarios
+
+Use `faf-expert` for:
+- 🎯 Fine-tuned championship scoring (95%+)
+- 🎯 Complex MCP server configuration
+- 🎯 Multi-platform sync management  
+- 🎯 Enterprise deployment patterns
+
+## Validation & Security
+
+**Enterprise-Grade Standards:**
+- ✅ **800+ comprehensive tests** across CLI and MCP
+- ✅ **No credentials ever stored** in .faf files
+- ✅ **YAML format validation** prevents malformed files
+- ✅ **IANA-registered format** (application/vnd.faf+yaml)
+- ✅ **MIT licensed** - safe for commercial use
+
+## Getting Started
+
+### For Your Current Project
+```bash
+# One command, done forever
+npx faf-cli auto
+
+# Check the results
+cat project.faf
+```
+
+### For Any GitHub Repository  
+Install the browser extension and click "Generate FAF" on any repo.
+
+### For Teams
+```bash
+# Set up team-wide MCP server
+faf mcp install --team
+faf sync --target all --watch
+```
+
+## Community & Support
+
+- **Website**: https://faf.one
+- **Chrome Extension**: 4.8★ rating, Google approved
+- **Downloads**: 52k+ across ecosystem  
+- **Discord**: Active community of 1000+ developers
+- **Documentation**: Comprehensive guides and examples
+
+---
+
+*Stop explaining your project every session. FAF Wizard - because AI should understand your project as well as you do.*

package/bundled-skills/file-uploads/SKILL.md

@@ -1,27 +1,228 @@
 ---
 name: file-uploads
-description: "Careful about security and performance. Never trusts file extensions. Knows that large uploads need special handling. Prefers presigned URLs over server proxying."
+description: Expert at handling file uploads and cloud storage. Covers S3,
+  Cloudflare R2, presigned URLs, multipart uploads, and image optimization.
+  Knows how to handle large files without blocking.
 risk: none
-source: "vibeship-spawner-skills (Apache 2.0)"
-date_added: "2026-02-27"
+source: vibeship-spawner-skills (Apache 2.0)
+date_added: 2026-02-27
 ---
 
 # File Uploads & Storage
 
+Expert at handling file uploads and cloud storage. Covers S3,
+Cloudflare R2, presigned URLs, multipart uploads, and image
+optimization. Knows how to handle large files without blocking.
+
 **Role**: File Upload Specialist
 
 Careful about security and performance. Never trusts file
 extensions. Knows that large uploads need special handling.
 Prefers presigned URLs over server proxying.
 
-## ⚠️ Sharp Edges
+### Principles
+
+- Never trust client file type claims
+- Use presigned URLs for direct uploads
+- Stream large files, never buffer
+- Validate on upload, optimize after
+
+## Sharp Edges
+
+### Trusting client-provided file type
+
+Severity: CRITICAL
+
+Situation: User uploads malware.exe renamed to image.jpg. You check
+extension, looks fine. Store it. Serve it. Another user
+downloads and executes it.
+
+Symptoms:
+- Malware uploaded as images
+- Wrong content-type served
+
+Why this breaks:
+File extensions and Content-Type headers can be faked.
+Attackers rename executables to bypass filters.
+
+Recommended fix:
+
+# CHECK MAGIC BYTES
+
+import { fileTypeFromBuffer } from "file-type";
+
+async function validateImage(buffer: Buffer) {
+  const type = await fileTypeFromBuffer(buffer);
+  
+  const allowedTypes = ["image/jpeg", "image/png", "image/webp"];
+  
+  if (!type || !allowedTypes.includes(type.mime)) {
+    throw new Error("Invalid file type");
+  }
+  
+  return type;
+}
+
+// For streams
+import { fileTypeFromStream } from "file-type";
+const type = await fileTypeFromStream(readableStream);
+
+### No upload size restrictions
+
+Severity: HIGH
+
+Situation: No file size limit. Attacker uploads 10GB file. Server runs
+out of memory or disk. Denial of service. Or massive
+storage bill.
+
+Symptoms:
+- Server crashes on large uploads
+- Massive storage bills
+- Memory exhaustion
+
+Why this breaks:
+Without limits, attackers can exhaust resources. Even
+legitimate users might accidentally upload huge files.
+
+Recommended fix:
+
+# SET SIZE LIMITS
+
+// Formidable
+const form = formidable({
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+});
+
+// Multer
+const upload = multer({
+  limits: { fileSize: 10 * 1024 * 1024 },
+});
+
+// Client-side early check
+if (file.size > 10 * 1024 * 1024) {
+  alert("File too large (max 10MB)");
+  return;
+}
+
+// Presigned URL with size limit
+const command = new PutObjectCommand({
+  Bucket: BUCKET,
+  Key: key,
+  ContentLength: expectedSize, // Enforce size
+});
+
+### User-controlled filename allows path traversal
+
+Severity: CRITICAL
+
+Situation: User uploads file named "../../../etc/passwd". You use
+filename directly. File saved outside upload directory.
+System files overwritten.
+
+Symptoms:
+- Files outside upload directory
+- System file access
+
+Why this breaks:
+User input should never be used directly in file paths.
+Path traversal sequences can escape intended directories.
 
-| Issue | Severity | Solution |
-|-------|----------|----------|
-| Trusting client-provided file type | critical | # CHECK MAGIC BYTES |
-| No upload size restrictions | high | # SET SIZE LIMITS |
-| User-controlled filename allows path traversal | critical | # SANITIZE FILENAMES |
-| Presigned URL shared or cached incorrectly | medium | # CONTROL PRESIGNED URL DISTRIBUTION |
+Recommended fix:
+
+# SANITIZE FILENAMES
+
+import path from "path";
+import crypto from "crypto";
+
+function safeFilename(userFilename: string): string {
+  // Extract just the base name
+  const base = path.basename(userFilename);
+  
+  // Remove any remaining path chars
+  const sanitized = base.replace(/[^a-zA-Z0-9.-]/g, "_");
+  
+  // Or better: generate new name entirely
+  const ext = path.extname(userFilename).toLowerCase();
+  const allowed = [".jpg", ".png", ".pdf"];
+  
+  if (!allowed.includes(ext)) {
+    throw new Error("Invalid extension");
+  }
+  
+  return crypto.randomUUID() + ext;
+}
+
+// Never do this
+const path = "uploads/" + req.body.filename; // DANGER!
+
+// Do this
+const path = "uploads/" + safeFilename(req.body.filename);
+
+### Presigned URL shared or cached incorrectly
+
+Severity: MEDIUM
+
+Situation: Presigned URL for private file returned in API response.
+Response cached by CDN. Anyone with cached URL can access
+private file for hours.
+
+Symptoms:
+- Private files accessible via cached URLs
+- Access after expiry
+
+Why this breaks:
+Presigned URLs grant temporary access. If cached or shared,
+access extends beyond intended scope.
+
+Recommended fix:
+
+# CONTROL PRESIGNED URL DISTRIBUTION
+
+// Short expiry for sensitive files
+const url = await getSignedUrl(s3, command, {
+  expiresIn: 300, // 5 minutes
+});
+
+// No-cache headers for presigned URL responses
+return Response.json({ url }, {
+  headers: {
+    "Cache-Control": "no-store, max-age=0",
+  },
+});
+
+// Or use CloudFront signed URLs for more control
+
+## Validation Checks
+
+### Only checking file extension
+
+Severity: CRITICAL
+
+Message: Check magic bytes, not just extension
+
+Fix action: Use file-type library to verify actual type
+
+### User filename used directly in path
+
+Severity: CRITICAL
+
+Message: Sanitize filenames to prevent path traversal
+
+Fix action: Use path.basename() and generate safe name
+
+## Collaboration
+
+### Delegation Triggers
+
+- image optimization CDN -> performance-optimization (Image delivery)
+- storing file metadata -> postgres-wizard (Database schema)
 
 ## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+
+- User mentions or implies: file upload
+- User mentions or implies: S3
+- User mentions or implies: R2
+- User mentions or implies: presigned URL
+- User mentions or implies: multipart
+- User mentions or implies: image upload
+- User mentions or implies: cloud storage