aigroup-workflow 2.1.2 → 2.2.0

package/skills/javascript-pro/references/node-essentials.md

@@ -1,471 +0,0 @@
-# Node.js Essentials
-
-## File System (fs/promises)
-
-```javascript
-import { readFile, writeFile, appendFile, mkdir, rm, readdir, stat } from 'fs/promises';
-import { existsSync } from 'fs';
-import { join, dirname } from 'path';
-
-// Read file
-const content = await readFile('./file.txt', 'utf-8');
-
-// Write file (overwrites)
-await writeFile('./output.txt', 'Hello World');
-
-// Append to file
-await appendFile('./log.txt', 'New log entry\n');
-
-// Read JSON file
-const readJSON = async (path) => {
-  const content = await readFile(path, 'utf-8');
-  return JSON.parse(content);
-};
-
-// Write JSON file
-const writeJSON = async (path, data) => {
-  await writeFile(path, JSON.stringify(data, null, 2));
-};
-
-// Create directory (recursive)
-await mkdir('./nested/path/dir', { recursive: true });
-
-// Remove directory/file (recursive)
-await rm('./temp', { recursive: true, force: true });
-
-// List directory
-const files = await readdir('./src');
-const filesWithTypes = await readdir('./src', { withFileTypes: true });
-
-for (const file of filesWithTypes) {
-  if (file.isDirectory()) {
-    console.log(`[DIR] ${file.name}`);
-  } else {
-    console.log(`[FILE] ${file.name}`);
-  }
-}
-
-// Get file stats
-const stats = await stat('./file.txt');
-console.log('Size:', stats.size);
-console.log('Modified:', stats.mtime);
-console.log('Is file:', stats.isFile());
-
-// Check existence (sync only)
-if (existsSync('./path')) {
-  // Path exists
-}
-```
-
-## Path Module
-
-```javascript
-import { join, resolve, dirname, basename, extname, parse, format } from 'path';
-import { fileURLToPath } from 'url';
-
-// Get current file and directory in ESM
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Join paths (platform-independent)
-const filePath = join(__dirname, 'data', 'config.json');
-
-// Resolve to absolute path
-const absolutePath = resolve('./relative/path');
-
-// Get filename
-const filename = basename('/path/to/file.txt'); // 'file.txt'
-const filenameNoExt = basename('/path/to/file.txt', '.txt'); // 'file'
-
-// Get extension
-const ext = extname('file.txt'); // '.txt'
-
-// Parse path
-const parsed = parse('/home/user/file.txt');
-// {
-//   root: '/',
-//   dir: '/home/user',
-//   base: 'file.txt',
-//   ext: '.txt',
-//   name: 'file'
-// }
-
-// Format path
-const formatted = format({
-  dir: '/home/user',
-  base: 'file.txt'
-}); // '/home/user/file.txt'
-```
-
-## Streams
-
-```javascript
-import { createReadStream, createWriteStream } from 'fs';
-import { pipeline } from 'stream/promises';
-import { Transform } from 'stream';
-
-// Read large file efficiently
-const readStream = createReadStream('./large-file.txt', {
-  encoding: 'utf-8',
-  highWaterMark: 16 * 1024 // 16KB chunks
-});
-
-readStream.on('data', (chunk) => {
-  console.log('Chunk:', chunk);
-});
-
-readStream.on('end', () => {
-  console.log('Finished reading');
-});
-
-readStream.on('error', (error) => {
-  console.error('Error:', error);
-});
-
-// Write stream
-const writeStream = createWriteStream('./output.txt');
-writeStream.write('Line 1\n');
-writeStream.write('Line 2\n');
-writeStream.end('Final line\n');
-
-// Pipe streams
-const input = createReadStream('./input.txt');
-const output = createWriteStream('./output.txt');
-input.pipe(output);
-
-// Transform stream
-const upperCaseTransform = new Transform({
-  transform(chunk, encoding, callback) {
-    const transformed = chunk.toString().toUpperCase();
-    callback(null, transformed);
-  }
-});
-
-await pipeline(
-  createReadStream('./input.txt'),
-  upperCaseTransform,
-  createWriteStream('./output.txt')
-);
-
-// Async iteration over stream
-const processStream = async (filePath) => {
-  const stream = createReadStream(filePath, { encoding: 'utf-8' });
-
-  for await (const chunk of stream) {
-    processChunk(chunk);
-  }
-};
-```
-
-## EventEmitter
-
-```javascript
-import { EventEmitter } from 'events';
-
-class DataProcessor extends EventEmitter {
-  async process(data) {
-    this.emit('start', { itemCount: data.length });
-
-    for (let i = 0; i < data.length; i++) {
-      await this.processItem(data[i]);
-      this.emit('progress', { current: i + 1, total: data.length });
-    }
-
-    this.emit('complete', { processed: data.length });
-  }
-
-  async processItem(item) {
-    // Processing logic
-    if (item.error) {
-      this.emit('error', new Error('Item processing failed'));
-    }
-  }
-}
-
-// Usage
-const processor = new DataProcessor();
-
-processor.on('start', ({ itemCount }) => {
-  console.log(`Starting processing ${itemCount} items`);
-});
-
-processor.on('progress', ({ current, total }) => {
-  console.log(`Progress: ${current}/${total}`);
-});
-
-processor.on('complete', ({ processed }) => {
-  console.log(`Completed: ${processed} items`);
-});
-
-processor.on('error', (error) => {
-  console.error('Processing error:', error);
-});
-
-// One-time listener
-processor.once('complete', () => {
-  console.log('First completion');
-});
-
-// Remove listener
-const handler = () => console.log('Event fired');
-processor.on('event', handler);
-processor.off('event', handler);
-```
-
-## Child Processes
-
-```javascript
-import { spawn, exec, execFile } from 'child_process';
-import { promisify } from 'util';
-
-const execAsync = promisify(exec);
-
-// Execute shell command
-const { stdout, stderr } = await execAsync('ls -la');
-console.log('Output:', stdout);
-
-// Spawn process with streaming
-const ls = spawn('ls', ['-la', '/usr']);
-
-ls.stdout.on('data', (data) => {
-  console.log(`stdout: ${data}`);
-});
-
-ls.stderr.on('data', (data) => {
-  console.error(`stderr: ${data}`);
-});
-
-ls.on('close', (code) => {
-  console.log(`Process exited with code ${code}`);
-});
-
-// Execute Node.js script
-const child = spawn('node', ['script.js'], {
-  cwd: './scripts',
-  env: { ...process.env, CUSTOM_VAR: 'value' }
-});
-```
-
-## Worker Threads
-
-```javascript
-import { Worker, isMainThread, parentPort, workerData } from 'worker_threads';
-
-if (isMainThread) {
-  // Main thread
-  const worker = new Worker(new URL(import.meta.url), {
-    workerData: { items: [1, 2, 3, 4, 5] }
-  });
-
-  worker.on('message', (result) => {
-    console.log('Result from worker:', result);
-  });
-
-  worker.on('error', (error) => {
-    console.error('Worker error:', error);
-  });
-
-  worker.on('exit', (code) => {
-    console.log(`Worker exited with code ${code}`);
-  });
-
-  worker.postMessage({ command: 'process' });
-} else {
-  // Worker thread
-  const { items } = workerData;
-
-  parentPort.on('message', (message) => {
-    if (message.command === 'process') {
-      const result = items.reduce((sum, n) => sum + n, 0);
-      parentPort.postMessage(result);
-    }
-  });
-}
-
-// Worker pool pattern
-class WorkerPool {
-  #workers = [];
-  #queue = [];
-
-  constructor(workerPath, poolSize = 4) {
-    for (let i = 0; i < poolSize; i++) {
-      this.#workers.push({
-        worker: new Worker(workerPath),
-        busy: false
-      });
-    }
-  }
-
-  async execute(data) {
-    return new Promise((resolve, reject) => {
-      const task = { data, resolve, reject };
-      this.#queue.push(task);
-      this.#processQueue();
-    });
-  }
-
-  #processQueue() {
-    const availableWorker = this.#workers.find(w => !w.busy);
-    if (!availableWorker || this.#queue.length === 0) return;
-
-    const task = this.#queue.shift();
-    availableWorker.busy = true;
-
-    const handleMessage = (result) => {
-      task.resolve(result);
-      availableWorker.busy = false;
-      availableWorker.worker.off('message', handleMessage);
-      this.#processQueue();
-    };
-
-    availableWorker.worker.on('message', handleMessage);
-    availableWorker.worker.postMessage(task.data);
-  }
-}
-```
-
-## Process & Environment
-
-```javascript
-// Environment variables
-const port = process.env.PORT || 3000;
-const isDev = process.env.NODE_ENV === 'development';
-
-// Command-line arguments
-const args = process.argv.slice(2);
-console.log('Arguments:', args);
-
-// Exit process
-process.exit(0); // Success
-process.exit(1); // Error
-
-// Graceful shutdown
-process.on('SIGINT', async () => {
-  console.log('Shutting down gracefully...');
-  await cleanup();
-  process.exit(0);
-});
-
-process.on('SIGTERM', async () => {
-  console.log('Received SIGTERM');
-  await cleanup();
-  process.exit(0);
-});
-
-// Unhandled errors
-process.on('uncaughtException', (error) => {
-  console.error('Uncaught exception:', error);
-  process.exit(1);
-});
-
-process.on('unhandledRejection', (reason, promise) => {
-  console.error('Unhandled rejection:', reason);
-  process.exit(1);
-});
-
-// Process info
-console.log('PID:', process.pid);
-console.log('Platform:', process.platform);
-console.log('Node version:', process.version);
-console.log('Memory usage:', process.memoryUsage());
-console.log('Uptime:', process.uptime());
-```
-
-## HTTP/HTTPS Server
-
-```javascript
-import { createServer } from 'http';
-import { readFile } from 'fs/promises';
-
-const server = createServer(async (req, res) => {
-  // Parse URL and method
-  const { url, method } = req;
-
-  // Set CORS headers
-  res.setHeader('Access-Control-Allow-Origin', '*');
-  res.setHeader('Content-Type', 'application/json');
-
-  // Route handling
-  if (url === '/api/users' && method === 'GET') {
-    const users = [{ id: 1, name: 'John' }];
-    res.writeHead(200);
-    res.end(JSON.stringify(users));
-  } else if (url === '/api/users' && method === 'POST') {
-    let body = '';
-
-    req.on('data', chunk => {
-      body += chunk.toString();
-    });
-
-    req.on('end', () => {
-      const user = JSON.parse(body);
-      res.writeHead(201);
-      res.end(JSON.stringify({ id: 2, ...user }));
-    });
-  } else {
-    res.writeHead(404);
-    res.end(JSON.stringify({ error: 'Not found' }));
-  }
-});
-
-server.listen(3000, () => {
-  console.log('Server running on http://localhost:3000');
-});
-
-// Graceful shutdown
-const shutdown = () => {
-  server.close(() => {
-    console.log('Server closed');
-    process.exit(0);
-  });
-};
-
-process.on('SIGTERM', shutdown);
-process.on('SIGINT', shutdown);
-```
-
-## Cluster for Multi-Core
-
-```javascript
-import cluster from 'cluster';
-import { cpus } from 'os';
-import { createServer } from 'http';
-
-const numCPUs = cpus().length;
-
-if (cluster.isPrimary) {
-  console.log(`Primary ${process.pid} is running`);
-
-  // Fork workers
-  for (let i = 0; i < numCPUs; i++) {
-    cluster.fork();
-  }
-
-  cluster.on('exit', (worker, code, signal) => {
-    console.log(`Worker ${worker.process.pid} died`);
-    cluster.fork(); // Restart worker
-  });
-} else {
-  // Workers share TCP connection
-  const server = createServer((req, res) => {
-    res.writeHead(200);
-    res.end(`Handled by worker ${process.pid}\n`);
-  });
-
-  server.listen(3000);
-  console.log(`Worker ${process.pid} started`);
-}
-```
-
-## Quick Reference
-
-| Module | Use Case | Import |
-|--------|----------|--------|
-| `fs/promises` | Async file operations | `import { readFile } from 'fs/promises'` |
-| `path` | Path manipulation | `import { join } from 'path'` |
-| `stream` | Stream processing | `import { pipeline } from 'stream/promises'` |
-| `events` | Event emitters | `import { EventEmitter } from 'events'` |
-| `child_process` | Spawn processes | `import { spawn } from 'child_process'` |
-| `worker_threads` | Multi-threading | `import { Worker } from 'worker_threads'` |
-| `http` | HTTP server | `import { createServer } from 'http'` |
-| `cluster` | Multi-core scaling | `import cluster from 'cluster'` |

package/skills/kotlin-specialist/SKILL.md

@@ -1,147 +0,0 @@
----
-name: kotlin-specialist
-description: Provides idiomatic Kotlin implementation patterns including coroutine concurrency, Flow stream handling, multiplatform architecture, Compose UI construction, Ktor server setup, and type-safe DSL design. Use when building Kotlin applications requiring coroutines, multiplatform development, or Android with Compose. Invoke for Flow API, KMP projects, Ktor servers, DSL design, sealed classes, suspend function, Android Kotlin, Kotlin Multiplatform.
-license: MIT
-metadata:
-  author: https://github.com/Jeffallan
-  version: "1.1.0"
-  domain: language
-  triggers: Kotlin, coroutines, Kotlin Multiplatform, KMP, Jetpack Compose, Ktor, Flow, Android Kotlin, suspend function
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: test-master
----
-
-# Kotlin Specialist
-
-Senior Kotlin developer with deep expertise in coroutines, Kotlin Multiplatform (KMP), and modern Kotlin 1.9+ patterns.
-
-## Core Workflow
-
-1. **Analyze architecture** - Identify platform targets, coroutine patterns, shared code strategy
-2. **Design models** - Create sealed classes, data classes, type hierarchies
-3. **Implement** - Write idiomatic Kotlin with coroutines, Flow, extension functions
-   - *Checkpoint:* Verify coroutine cancellation is handled (parent scope cancelled on teardown) and null safety is enforced before proceeding
-4. **Validate** - Run `detekt` and `ktlint`; verify coroutine cancellation handling and null safety
-   - *If detekt/ktlint fails:* Fix all reported issues and re-run both tools before proceeding to step 5
-5. **Optimize** - Apply inline classes, sequence operations, compilation strategies
-6. **Test** - Write multiplatform tests with coroutine test support (`runTest`, Turbine)
-
-## Reference Guide
-
-Load detailed guidance based on context:
-
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Coroutines & Flow | `references/coroutines-flow.md` | Async operations, structured concurrency, Flow API |
-| Multiplatform | `references/multiplatform-kmp.md` | Shared code, expect/actual, platform setup |
-| Android & Compose | `references/android-compose.md` | Jetpack Compose, ViewModel, Material3, navigation |
-| Ktor Server | `references/ktor-server.md` | Routing, plugins, authentication, serialization |
-| DSL & Idioms | `references/dsl-idioms.md` | Type-safe builders, scope functions, delegates |
-
-## Key Patterns
-
-### Sealed Classes for State Modeling
-
-```kotlin
-sealed class UiState<out T> {
-    data object Loading : UiState<Nothing>()
-    data class Success<T>(val data: T) : UiState<T>()
-    data class Error(val message: String, val cause: Throwable? = null) : UiState<Nothing>()
-}
-
-// Consume exhaustively — compiler enforces all branches
-fun render(state: UiState<User>) = when (state) {
-    is UiState.Loading  -> showSpinner()
-    is UiState.Success  -> showUser(state.data)
-    is UiState.Error    -> showError(state.message)
-}
-```
-
-### Coroutines & Flow
-
-```kotlin
-// Use structured concurrency — never GlobalScope
-class UserRepository(private val api: UserApi, private val scope: CoroutineScope) {
-
-    fun userUpdates(id: String): Flow<UiState<User>> = flow {
-        emit(UiState.Loading)
-        try {
-            emit(UiState.Success(api.fetchUser(id)))
-        } catch (e: IOException) {
-            emit(UiState.Error("Network error", e))
-        }
-    }.flowOn(Dispatchers.IO)
-
-    private val _user = MutableStateFlow<UiState<User>>(UiState.Loading)
-    val user: StateFlow<UiState<User>> = _user.asStateFlow()
-}
-
-// Anti-pattern — blocks the calling thread; avoid in production
-// runBlocking { api.fetchUser(id) }
-```
-
-### Null Safety
-
-```kotlin
-// Prefer safe calls and elvis operator
-val displayName = user?.profile?.name ?: "Anonymous"
-
-// Use let to scope nullable operations
-user?.email?.let { email -> sendNotification(email) }
-
-// !! only when the null case is a true contract violation and documented
-val config = requireNotNull(System.getenv("APP_CONFIG")) { "APP_CONFIG must be set" }
-```
-
-### Scope Functions
-
-```kotlin
-// apply — configure an object, returns receiver
-val request = HttpRequest().apply {
-    url = "https://api.example.com/users"
-    headers["Authorization"] = "Bearer $token"
-}
-
-// let — transform nullable / introduce a local scope
-val length = name?.let { it.trim().length } ?: 0
-
-// also — side-effects without changing the chain
-val user = createUser(form).also { logger.info("Created user ${it.id}") }
-```
-
-## Constraints
-
-### MUST DO
-- Use null safety (`?`, `?.`, `?:`, `!!` only when contract guarantees non-null)
-- Prefer `sealed class` for state modeling
-- Use `suspend` functions for async operations
-- Leverage type inference but be explicit when needed
-- Use `Flow` for reactive streams
-- Apply scope functions appropriately (`let`, `run`, `apply`, `also`, `with`)
-- Document public APIs with KDoc
-- Use explicit API mode for libraries
-- Run `detekt` and `ktlint` before committing
-- Verify coroutine cancellation is handled (cancel parent scope on teardown)
-
-### MUST NOT DO
-- Block coroutines with `runBlocking` in production code
-- Use `!!` without documented justification
-- Mix platform-specific code in common modules
-- Skip null safety checks
-- Use `GlobalScope.launch` (use structured concurrency)
-- Ignore coroutine cancellation
-- Create memory leaks with coroutine scopes
-
-## Output Templates
-
-When implementing Kotlin features, provide:
-1. Data models (sealed classes, data classes)
-2. Implementation file (extension functions, suspend functions)
-3. Test file with coroutine test support
-4. Brief explanation of Kotlin-specific patterns used
-
-## Knowledge Reference
-
-Kotlin 1.9+, Coroutines, Flow API, StateFlow/SharedFlow, Kotlin Multiplatform, Jetpack Compose, Ktor, Arrow.kt, kotlinx.serialization, Detekt, ktlint, Gradle Kotlin DSL, JUnit 5, MockK, Turbine