@namch/agent-assistant 1.0.0

package/skills/cloudflare-expert/references/zaraz/README.md

@@ -0,0 +1,360 @@
+# Cloudflare Zaraz Skill
+
+Expert guidance for Cloudflare Zaraz - server-side tag manager for loading third-party tools at the edge.
+
+## What is Zaraz?
+
+Zaraz offloads third-party scripts (analytics, ads, chat, marketing) to Cloudflare's edge, improving site speed, privacy, and security. Zero client-side performance impact.
+
+## Core Concepts
+
+- **Server-side execution** - Scripts run on Cloudflare, not user's browser
+- **Single HTTP request** - All tools loaded via one endpoint
+- **Privacy-first** - Control data sent to third parties
+- **No client-side JS** - Minimal browser overhead
+
+## Zaraz Dashboard Setup
+
+1. Navigate to domain > Zaraz
+2. Click "Start setup"
+3. Add tools (Google Analytics, Facebook Pixel, etc.)
+4. Configure triggers and actions
+
+## Web API
+
+Zaraz provides `zaraz` object in browser:
+
+### Track Events
+
+```javascript
+// Basic event
+zaraz.track('button_click');
+
+// Event with properties
+zaraz.track('purchase', {
+  value: 99.99,
+  currency: 'USD',
+  item_id: '12345'
+});
+
+// E-commerce events
+zaraz.track('add_to_cart', {
+  product_name: 'Widget',
+  price: 29.99,
+  quantity: 1
+});
+```
+
+### Set User Properties
+
+```javascript
+zaraz.set('userId', 'user_12345');
+zaraz.set('plan', 'premium');
+zaraz.set({
+  email: '[email protected]',
+  country: 'US',
+  age: 30
+});
+```
+
+### E-commerce Tracking
+
+```javascript
+// Product view
+zaraz.ecommerce('Product Viewed', {
+  product_id: 'SKU123',
+  name: 'Blue Widget',
+  price: 49.99,
+  currency: 'USD'
+});
+
+// Add to cart
+zaraz.ecommerce('Product Added', {
+  product_id: 'SKU123',
+  quantity: 2,
+  price: 49.99
+});
+
+// Purchase
+zaraz.ecommerce('Order Completed', {
+  order_id: 'ORD-789',
+  total: 149.98,
+  revenue: 149.98,
+  shipping: 10.00,
+  tax: 12.50,
+  currency: 'USD',
+  products: [
+    { product_id: 'SKU123', quantity: 2, price: 49.99 }
+  ]
+});
+```
+
+## Consent Management
+
+```javascript
+// Check consent status
+if (zaraz.consent.getAll().analytics) {
+  zaraz.track('page_view');
+}
+
+// Request consent
+zaraz.consent.modal = true; // Show consent modal
+
+// Set consent programmatically
+zaraz.consent.setAll({
+  analytics: true,
+  marketing: false,
+  preferences: true
+});
+
+// Listen for consent changes
+zaraz.consent.addEventListener('consentChanged', () => {
+  console.log('Consent updated:', zaraz.consent.getAll());
+});
+```
+
+## Workers Integration
+
+Access Zaraz data in Workers:
+
+```typescript
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    
+    // Inject Zaraz tracking
+    if (url.pathname === '/checkout') {
+      const response = await fetch(req);
+      const html = await response.text();
+      
+      const tracking = `
+        <script>
+          zaraz.track('checkout_started', {
+            cart_value: 99.99
+          });
+        </script>
+      `;
+      
+      const modified = html.replace('</body>', tracking + '</body>');
+      return new Response(modified, response);
+    }
+    
+    return fetch(req);
+  }
+};
+```
+
+## Triggers
+
+Configure when tools fire:
+
+### Page Rules
+
+- **Pageview** - On every page load
+- **DOM Ready** - When DOM is ready
+- **Click** - Element clicks (CSS selector)
+- **Form submission** - Form submits
+- **Scroll depth** - User scrolls percentage
+- **Timer** - After time elapsed
+- **Variable match** - Custom conditions
+
+### Example Trigger
+
+```
+Trigger: Button Click
+Match rule: CSS Selector = .buy-button
+Action: Track event "purchase_intent"
+```
+
+## Common Tools
+
+### Google Analytics 4
+
+```javascript
+// Track page view (automatic)
+zaraz.track('pageview');
+
+// Custom event
+zaraz.track('sign_up', {
+  method: 'email'
+});
+```
+
+### Facebook Pixel
+
+```javascript
+zaraz.track('PageView');
+zaraz.track('Purchase', {
+  value: 99.99,
+  currency: 'USD'
+});
+```
+
+### Google Ads Conversion
+
+```javascript
+zaraz.track('conversion', {
+  send_to: 'AW-XXXXXXXXX/YYYYYY',
+  value: 1.00,
+  currency: 'USD'
+});
+```
+
+## Custom Managed Components
+
+Build custom tools:
+
+```javascript
+// Example: Custom analytics tool
+export default class CustomAnalytics {
+  async handleEvent(event) {
+    const { type, payload } = event;
+    
+    await fetch('https://analytics.example.com/track', {
+      method: 'POST',
+      body: JSON.stringify({
+        event: type,
+        properties: payload,
+        timestamp: Date.now()
+      })
+    });
+  }
+}
+```
+
+## Data Layer
+
+Use `zaraz.dataLayer` for structured data:
+
+```javascript
+// Set data layer
+window.zaraz.dataLayer = {
+  user_id: '12345',
+  page_type: 'product',
+  category: 'electronics'
+};
+
+// Access in triggers
+// Variable: {{client.__zarazTrack.page_type}}
+```
+
+## Server-Side Configuration
+
+### zaraz.toml
+
+```toml
+[settings]
+auto_inject = true
+debug_mode = false
+
+[[tools]]
+type = "google-analytics"
+id = "G-XXXXXXXXXX"
+
+[[tools.triggers]]
+match_rule = "Pageview"
+```
+
+## Privacy Features
+
+1. **IP anonymization** - Automatic
+2. **Cookie control** - Consent-based
+3. **Data minimization** - Send only necessary data
+4. **Regional compliance** - GDPR, CCPA support
+
+## Performance
+
+```javascript
+// Zaraz automatically:
+// - Batches requests
+// - Defers non-critical scripts
+// - Proxies third-party requests
+// - Caches tool configurations
+
+// Result: ~0ms client-side overhead
+```
+
+## Debugging
+
+```javascript
+// Enable debug mode in dashboard, then:
+zaraz.debug = true;
+
+// View events in console
+zaraz.track('test_event', { debug: true });
+
+// Check loaded tools
+console.log(zaraz.tools);
+```
+
+## Best Practices
+
+1. **Use triggers** instead of inline `zaraz.track()` when possible
+2. **Batch events** for related actions
+3. **Test with debug mode** before production
+4. **Implement consent** for GDPR compliance
+5. **Monitor performance** in dashboard analytics
+6. **Use data layer** for structured data
+
+## Common Patterns
+
+### SPA Tracking
+
+```javascript
+// On route change
+router.afterEach((to, from) => {
+  zaraz.track('pageview', {
+    page_path: to.path,
+    page_title: to.meta.title
+  });
+});
+```
+
+### User Identification
+
+```javascript
+// On login
+zaraz.set('user_id', user.id);
+zaraz.set('user_email', user.email);
+zaraz.track('login', { method: 'password' });
+```
+
+### A/B Testing
+
+```javascript
+const variant = Math.random() < 0.5 ? 'A' : 'B';
+zaraz.set('ab_test_variant', variant);
+zaraz.track('ab_test_view', { variant });
+```
+
+## Limits
+
+- **Tools**: Unlimited
+- **Events**: Unlimited
+- **Data retention**: Per tool's policy
+- **Request size**: 100KB per request
+
+## Troubleshooting
+
+### Events not firing
+
+- Check trigger conditions in dashboard
+- Verify tool is enabled
+- Enable debug mode
+- Check browser console for errors
+
+### Consent issues
+
+- Verify consent modal configuration
+- Check `zaraz.consent.getAll()` status
+- Ensure tools respect consent settings
+
+## Reference
+
+- [Zaraz Docs](https://developers.cloudflare.com/zaraz/)
+- [Web API](https://developers.cloudflare.com/zaraz/web-api/)
+- [Managed Components](https://developers.cloudflare.com/zaraz/advanced/load-custom-managed-component/)
+
+---
+
+This skill focuses exclusively on Zaraz. For Workers development, see `cloudflare-workers` skill.

package/skills/code-documentation/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: code-documentation
+description: Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
+source: wshobson/agents
+license: MIT
+---
+
+# Code Documentation
+
+## README Structure
+
+### Standard README Template
+```markdown
+# Project Name
+
+Brief description of what this project does.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Installation
+
+Detailed installation instructions...
+
+## Usage
+
+\`\`\`typescript
+import { something } from 'project';
+
+// Example usage
+const result = something.doThing();
+\`\`\`
+
+## API Reference
+
+### `functionName(param: Type): ReturnType`
+
+Description of what the function does.
+
+**Parameters:**
+- `param` - Description of parameter
+
+**Returns:** Description of return value
+
+**Example:**
+\`\`\`typescript
+const result = functionName('value');
+\`\`\`
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option1` | `string` | `'default'` | What it does |
+
+## Contributing
+
+How to contribute...
+
+## License
+
+MIT
+```
+
+## API Documentation
+
+### JSDoc/TSDoc Style
+```typescript
+/**
+ * Creates a new user account.
+ *
+ * @param userData - The user data for account creation
+ * @param options - Optional configuration
+ * @returns The created user object
+ * @throws {ValidationError} If email is invalid
+ * @example
+ * ```ts
+ * const user = await createUser({
+ *   email: 'user@example.com',
+ *   name: 'John'
+ * });
+ * ```
+ */
+async function createUser(
+  userData: UserInput,
+  options?: CreateOptions
+): Promise<User> {
+  // Implementation
+}
+
+/**
+ * Configuration options for the API client.
+ */
+interface ClientConfig {
+  /** The API base URL */
+  baseUrl: string;
+  /** Request timeout in milliseconds @default 5000 */
+  timeout?: number;
+  /** Custom headers to include in requests */
+  headers?: Record<string, string>;
+}
+```
+
+### OpenAPI/Swagger
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+
+paths:
+  /users:
+    post:
+      summary: Create a user
+      description: Creates a new user account
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserInput'
+      responses:
+        '201':
+          description: User created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '400':
+          description: Invalid input
+
+components:
+  schemas:
+    UserInput:
+      type: object
+      required:
+        - email
+        - name
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        name:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+```
+
+## Inline Comments
+
+### When to Comment
+```typescript
+// GOOD: Explain WHY, not WHAT
+
+// Use binary search because the list is always sorted and
+// can contain millions of items - O(log n) vs O(n)
+const index = binarySearch(items, target);
+
+// GOOD: Explain complex business logic
+// Users get 20% discount if they've been members for 2+ years
+// AND have made 10+ purchases (per marketing team decision Q4 2024)
+if (user.memberYears >= 2 && user.purchaseCount >= 10) {
+  applyDiscount(0.2);
+}
+
+// GOOD: Document workarounds
+// HACK: Safari doesn't support this API, fallback to polling
+// TODO: Remove when Safari adds support (tracking: webkit.org/b/12345)
+if (!window.IntersectionObserver) {
+  startPolling();
+}
+```
+
+### When NOT to Comment
+```typescript
+// BAD: Stating the obvious
+// Increment counter by 1
+counter++;
+
+// BAD: Explaining clear code
+// Check if user is admin
+if (user.role === 'admin') { ... }
+
+// BAD: Outdated comments (worse than no comment)
+// Returns the user's full name  <-- Actually returns email now!
+function getUserIdentifier(user) {
+  return user.email;
+}
+```
+
+## Architecture Documentation
+
+### ADR (Architecture Decision Record)
+```markdown
+# ADR-001: Use PostgreSQL for Primary Database
+
+## Status
+Accepted
+
+## Context
+We need a database for storing user data and transactions.
+Options considered: PostgreSQL, MySQL, MongoDB, DynamoDB.
+
+## Decision
+Use PostgreSQL with Supabase hosting.
+
+## Rationale
+- Strong ACID compliance needed for financial data
+- Team has PostgreSQL experience
+- Supabase provides auth and realtime features
+- pgvector extension for future AI features
+
+## Consequences
+- Need to manage schema migrations
+- May need read replicas for scale
+- Team needs to learn Supabase-specific features
+```
+
+### Component Documentation
+```markdown
+## Authentication Module
+
+### Overview
+Handles user authentication using JWT tokens with refresh rotation.
+
+### Flow
+1. User submits credentials to `/auth/login`
+2. Server validates and returns access + refresh tokens
+3. Access token used for API requests (15min expiry)
+4. Refresh token used to get new access token (7d expiry)
+
+### Dependencies
+- `jsonwebtoken` - Token generation/validation
+- `bcrypt` - Password hashing
+- `redis` - Refresh token storage
+
+### Configuration
+- `JWT_SECRET` - Secret for signing tokens
+- `ACCESS_TOKEN_EXPIRY` - Access token lifetime
+- `REFRESH_TOKEN_EXPIRY` - Refresh token lifetime
+```
+
+## Documentation Principles
+
+1. **Write for your audience** - New devs vs API consumers
+2. **Keep it close to code** - Docs in same repo, near relevant code
+3. **Update with code** - Stale docs are worse than none
+4. **Examples over explanations** - Show, don't just tell
+5. **Progressive disclosure** - Quick start first, details later

package/skills/code-documenter/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: code-documenter
+description: Use when adding docstrings, creating API documentation, or building documentation sites. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, tutorials, user guides.
+triggers:
+  - documentation
+  - docstrings
+  - OpenAPI
+  - Swagger
+  - JSDoc
+  - comments
+  - API docs
+  - tutorials
+  - user guides
+  - doc site
+role: specialist
+scope: implementation
+output-format: code
+---
+
+# Code Documenter
+
+Documentation specialist for inline documentation, API specs, documentation sites, and developer guides.
+
+## Role Definition
+
+You are a senior technical writer with 8+ years of experience documenting software. You specialize in language-specific docstring formats, OpenAPI/Swagger specifications, interactive documentation portals, static site generation, and creating comprehensive guides that developers actually use.
+
+## When to Use This Skill
+
+- Adding docstrings to functions and classes
+- Creating OpenAPI/Swagger documentation
+- Building documentation sites (Docusaurus, MkDocs, VitePress)
+- Documenting APIs with framework-specific patterns
+- Creating interactive API portals (Swagger UI, Redoc, Stoplight)
+- Writing getting started guides and tutorials
+- Documenting multi-protocol APIs (REST, GraphQL, WebSocket, gRPC)
+- Generating documentation reports and coverage metrics
+
+## Core Workflow
+
+1. **Discover** - Ask for format preference and exclusions
+2. **Detect** - Identify language and framework
+3. **Analyze** - Find undocumented code
+4. **Document** - Apply consistent format
+5. **Report** - Generate coverage summary
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Python Docstrings | `references/python-docstrings.md` | Google, NumPy, Sphinx styles |
+| TypeScript JSDoc | `references/typescript-jsdoc.md` | JSDoc patterns, TypeScript |
+| FastAPI/Django API | `references/api-docs-fastapi-django.md` | Python API documentation |
+| NestJS/Express API | `references/api-docs-nestjs-express.md` | Node.js API documentation |
+| Coverage Reports | `references/coverage-reports.md` | Generating documentation reports |
+| Documentation Systems | `references/documentation-systems.md` | Doc sites, static generators, search, testing |
+| Interactive API Docs | `references/interactive-api-docs.md` | OpenAPI 3.1, portals, GraphQL, WebSocket, gRPC, SDKs |
+| User Guides & Tutorials | `references/user-guides-tutorials.md` | Getting started, tutorials, troubleshooting, FAQs |
+
+## Constraints
+
+### MUST DO
+- Ask for format preference before starting
+- Detect framework for correct API doc strategy
+- Document all public functions/classes
+- Include parameter types and descriptions
+- Document exceptions/errors
+- Test code examples in documentation
+- Generate coverage report
+
+### MUST NOT DO
+- Assume docstring format without asking
+- Apply wrong API doc strategy for framework
+- Write inaccurate or untested documentation
+- Skip error documentation
+- Document obvious getters/setters verbosely
+- Create documentation that's hard to maintain
+
+## Output Formats
+
+Depending on the task, provide:
+1. **Code Documentation:** Documented files + coverage report
+2. **API Docs:** OpenAPI specs + portal configuration
+3. **Doc Sites:** Site configuration + content structure + build instructions
+4. **Guides/Tutorials:** Structured markdown with examples + diagrams
+
+## Knowledge Reference
+
+Google/NumPy/Sphinx docstrings, JSDoc, OpenAPI 3.0/3.1, AsyncAPI, gRPC/protobuf, FastAPI, Django, NestJS, Express, GraphQL, Docusaurus, MkDocs, VitePress, Swagger UI, Redoc, Stoplight
+
+## Related Skills
+
+**Spec Miner** - Informs from code analysis | **Fullstack Guardian** - Documents during implementation | **Code Reviewer** - Checks documentation quality