aigroup-workflow 2.1.1 → 2.2.0

package/skills/websocket-engineer/references/security.md

@@ -1,474 +0,0 @@
-# WebSocket Security Reference
-
-## Authentication
-
-### JWT Authentication
-
-```javascript
-const io = require('socket.io')(3000);
-const jwt = require('jsonwebtoken');
-
-// Middleware for authentication
-io.use((socket, next) => {
-  const token = socket.handshake.auth.token;
-
-  if (!token) {
-    return next(new Error('Authentication error: No token provided'));
-  }
-
-  try {
-    const decoded = jwt.verify(token, process.env.JWT_SECRET);
-    socket.userId = decoded.userId;
-    socket.username = decoded.username;
-    next();
-  } catch (err) {
-    next(new Error('Authentication error: Invalid token'));
-  }
-});
-
-io.on('connection', (socket) => {
-  console.log(`User ${socket.username} connected`);
-
-  socket.on('message', (data) => {
-    // socket.userId is already verified
-    saveMessage(socket.userId, data);
-  });
-});
-```
-
-### Query Parameter Authentication (Less Secure)
-
-```javascript
-// Use only for initial handshake, then upgrade to token
-io.use((socket, next) => {
-  const token = socket.handshake.query.token;
-
-  if (!token) {
-    return next(new Error('Authentication required'));
-  }
-
-  jwt.verify(token, process.env.JWT_SECRET, (err, decoded) => {
-    if (err) return next(new Error('Invalid token'));
-    socket.userId = decoded.userId;
-    next();
-  });
-});
-```
-
-### Cookie Authentication
-
-```javascript
-const cookieParser = require('cookie-parser');
-
-io.use((socket, next) => {
-  const cookies = socket.handshake.headers.cookie;
-
-  if (!cookies) {
-    return next(new Error('No cookies'));
-  }
-
-  // Parse cookies
-  cookieParser(process.env.COOKIE_SECRET)(
-    socket.request,
-    {},
-    () => {
-      const sessionId = socket.request.signedCookies.sessionId;
-
-      if (!sessionId) {
-        return next(new Error('No session'));
-      }
-
-      // Verify session in Redis/DB
-      verifySession(sessionId).then(user => {
-        socket.userId = user.id;
-        next();
-      }).catch(err => {
-        next(new Error('Invalid session'));
-      });
-    }
-  );
-});
-```
-
-## Authorization
-
-### Room-Based Authorization
-
-```javascript
-io.on('connection', (socket) => {
-  socket.on('join-room', async (roomId) => {
-    // Check if user has permission
-    const hasAccess = await checkRoomAccess(socket.userId, roomId);
-
-    if (!hasAccess) {
-      socket.emit('error', { message: 'Access denied to room' });
-      return;
-    }
-
-    socket.join(roomId);
-    socket.emit('joined', { room: roomId });
-  });
-
-  socket.on('send-message', async ({ roomId, text }) => {
-    // Verify user is in room
-    if (!socket.rooms.has(roomId)) {
-      socket.emit('error', { message: 'Not in room' });
-      return;
-    }
-
-    // Check write permissions
-    const canWrite = await checkWritePermission(socket.userId, roomId);
-
-    if (!canWrite) {
-      socket.emit('error', { message: 'No write permission' });
-      return;
-    }
-
-    io.to(roomId).emit('message', {
-      userId: socket.userId,
-      text,
-      timestamp: Date.now()
-    });
-  });
-});
-```
-
-### Admin-Only Events
-
-```javascript
-const ADMIN_EVENTS = ['kick-user', 'ban-user', 'delete-message'];
-
-io.use((socket, next) => {
-  // Attach role to socket after auth
-  getUserRole(socket.userId).then(role => {
-    socket.role = role;
-    next();
-  });
-});
-
-io.on('connection', (socket) => {
-  ADMIN_EVENTS.forEach(event => {
-    socket.on(event, async (data) => {
-      if (socket.role !== 'admin') {
-        socket.emit('error', { message: 'Admin access required' });
-        return;
-      }
-
-      // Execute admin action
-      await handleAdminAction(event, data);
-    });
-  });
-});
-```
-
-## Rate Limiting
-
-### Per-Socket Rate Limiting
-
-```javascript
-const rateLimit = require('express-rate-limit');
-
-class SocketRateLimiter {
-  constructor(maxRequests = 100, windowMs = 60000) {
-    this.maxRequests = maxRequests;
-    this.windowMs = windowMs;
-    this.requests = new Map();
-  }
-
-  check(socketId) {
-    const now = Date.now();
-    const userRequests = this.requests.get(socketId) || [];
-
-    // Remove expired requests
-    const validRequests = userRequests.filter(
-      time => now - time < this.windowMs
-    );
-
-    if (validRequests.length >= this.maxRequests) {
-      return false; // Rate limit exceeded
-    }
-
-    validRequests.push(now);
-    this.requests.set(socketId, validRequests);
-    return true;
-  }
-
-  reset(socketId) {
-    this.requests.delete(socketId);
-  }
-}
-
-const limiter = new SocketRateLimiter(100, 60000); // 100 req/min
-
-io.on('connection', (socket) => {
-  socket.on('message', (data) => {
-    if (!limiter.check(socket.id)) {
-      socket.emit('error', { message: 'Rate limit exceeded' });
-      return;
-    }
-
-    // Process message
-    io.to(data.roomId).emit('message', data);
-  });
-
-  socket.on('disconnect', () => {
-    limiter.reset(socket.id);
-  });
-});
-```
-
-### Redis-Based Distributed Rate Limiting
-
-```javascript
-const Redis = require('ioredis');
-const redis = new Redis();
-
-async function checkRateLimit(userId, maxRequests = 100, windowSec = 60) {
-  const key = `rate_limit:${userId}`;
-  const now = Date.now();
-  const windowStart = now - (windowSec * 1000);
-
-  const pipeline = redis.pipeline();
-
-  // Remove old entries
-  pipeline.zremrangebyscore(key, 0, windowStart);
-
-  // Count requests in window
-  pipeline.zcard(key);
-
-  // Add current request
-  pipeline.zadd(key, now, `${now}-${Math.random()}`);
-
-  // Set expiry
-  pipeline.expire(key, windowSec);
-
-  const results = await pipeline.exec();
-  const count = results[1][1];
-
-  return count < maxRequests;
-}
-
-io.on('connection', (socket) => {
-  socket.on('message', async (data) => {
-    const allowed = await checkRateLimit(socket.userId, 50, 60);
-
-    if (!allowed) {
-      socket.emit('error', { message: 'Too many requests' });
-      return;
-    }
-
-    io.to(data.roomId).emit('message', data);
-  });
-});
-```
-
-## CORS Configuration
-
-```javascript
-const io = require('socket.io')(3000, {
-  cors: {
-    origin: ['https://example.com', 'https://app.example.com'],
-    methods: ['GET', 'POST'],
-    credentials: true,
-    allowedHeaders: ['Authorization']
-  }
-});
-
-// Dynamic CORS
-io.engine.on('initial_headers', (headers, req) => {
-  headers['Access-Control-Allow-Origin'] = req.headers.origin;
-});
-```
-
-## Input Validation
-
-```javascript
-const Joi = require('joi');
-
-const messageSchema = Joi.object({
-  roomId: Joi.string().uuid().required(),
-  text: Joi.string().min(1).max(1000).required(),
-  attachments: Joi.array().items(Joi.string().uri()).max(5).optional()
-});
-
-io.on('connection', (socket) => {
-  socket.on('message', (data) => {
-    // Validate input
-    const { error, value } = messageSchema.validate(data);
-
-    if (error) {
-      socket.emit('error', {
-        message: 'Invalid message format',
-        details: error.details
-      });
-      return;
-    }
-
-    // Process validated data
-    io.to(value.roomId).emit('message', {
-      userId: socket.userId,
-      ...value,
-      timestamp: Date.now()
-    });
-  });
-});
-```
-
-## XSS Protection
-
-```javascript
-const sanitizeHtml = require('sanitize-html');
-
-function sanitizeMessage(text) {
-  return sanitizeHtml(text, {
-    allowedTags: [], // Strip all HTML
-    allowedAttributes: {},
-    disallowedTagsMode: 'escape'
-  });
-}
-
-io.on('connection', (socket) => {
-  socket.on('message', (data) => {
-    const sanitized = {
-      ...data,
-      text: sanitizeMessage(data.text)
-    };
-
-    io.to(data.roomId).emit('message', sanitized);
-  });
-});
-```
-
-## DDoS Protection
-
-### Connection Limiting
-
-```javascript
-const connectionLimits = new Map();
-const MAX_CONNECTIONS_PER_IP = 10;
-
-io.engine.on('connection', (rawSocket) => {
-  const ip = rawSocket.request.headers['x-forwarded-for'] ||
-              rawSocket.request.connection.remoteAddress;
-
-  const currentConnections = connectionLimits.get(ip) || 0;
-
-  if (currentConnections >= MAX_CONNECTIONS_PER_IP) {
-    rawSocket.close(1008, 'Too many connections from IP');
-    return;
-  }
-
-  connectionLimits.set(ip, currentConnections + 1);
-
-  rawSocket.on('close', () => {
-    const count = connectionLimits.get(ip) - 1;
-    if (count <= 0) {
-      connectionLimits.delete(ip);
-    } else {
-      connectionLimits.set(ip, count);
-    }
-  });
-});
-```
-
-### Message Size Limits
-
-```javascript
-const io = require('socket.io')(3000, {
-  maxHttpBufferSize: 1e6, // 1MB max message size
-  pingTimeout: 60000,
-  pingInterval: 25000
-});
-
-io.on('connection', (socket) => {
-  socket.on('message', (data) => {
-    if (JSON.stringify(data).length > 10000) {
-      socket.emit('error', { message: 'Message too large' });
-      return;
-    }
-
-    // Process message
-  });
-});
-```
-
-## Secure Session Management
-
-```javascript
-const sessions = new Map();
-
-io.on('connection', (socket) => {
-  const sessionId = generateSecureSessionId();
-
-  sessions.set(socket.id, {
-    sessionId,
-    userId: socket.userId,
-    createdAt: Date.now(),
-    lastActivity: Date.now()
-  });
-
-  // Timeout inactive sessions
-  const timeout = setTimeout(() => {
-    socket.disconnect(true);
-  }, 30 * 60 * 1000); // 30 minutes
-
-  socket.on('message', () => {
-    const session = sessions.get(socket.id);
-    if (session) {
-      session.lastActivity = Date.now();
-      clearTimeout(timeout);
-    }
-  });
-
-  socket.on('disconnect', () => {
-    sessions.delete(socket.id);
-    clearTimeout(timeout);
-  });
-});
-
-function generateSecureSessionId() {
-  return require('crypto').randomBytes(32).toString('hex');
-}
-```
-
-## Audit Logging
-
-```javascript
-const winston = require('winston');
-
-const logger = winston.createLogger({
-  level: 'info',
-  format: winston.format.json(),
-  transports: [
-    new winston.transports.File({ filename: 'websocket-audit.log' })
-  ]
-});
-
-io.on('connection', (socket) => {
-  logger.info('Connection', {
-    socketId: socket.id,
-    userId: socket.userId,
-    ip: socket.handshake.address,
-    timestamp: Date.now()
-  });
-
-  socket.on('message', (data) => {
-    logger.info('Message', {
-      socketId: socket.id,
-      userId: socket.userId,
-      roomId: data.roomId,
-      messageLength: data.text.length,
-      timestamp: Date.now()
-    });
-  });
-
-  socket.on('disconnect', (reason) => {
-    logger.info('Disconnect', {
-      socketId: socket.id,
-      userId: socket.userId,
-      reason,
-      timestamp: Date.now()
-    });
-  });
-});
-```

package/skills/writing-plans/SKILL.md

@@ -1,151 +0,0 @@
----
-name: writing-plans
-description: Use when you have a spec or requirements for a multi-step task, before touching code
----
-
-# Writing Plans
-
-## Overview
-
-Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
-
-Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
-
-**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
-
-**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
-
-**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
-- (User preferences for plan location override this default)
-
-## Scope Check
-
-If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
-
-## File Structure
-
-Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
-
-- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
-- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
-- Files that change together should live together. Split by responsibility, not by technical layer.
-- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
-
-This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
-
-## Bite-Sized Task Granularity
-
-**Each step is one action (2-5 minutes):**
-- "Write the failing test" - step
-- "Run it to make sure it fails" - step
-- "Implement the minimal code to make the test pass" - step
-- "Run the tests and make sure they pass" - step
-- "Commit" - step
-
-## Plan Document Header
-
-**Every plan MUST start with this header:**
-
-```markdown
-# [Feature Name] Implementation Plan
-
-> **For agentic workers:** Dispatch subagents per the rules in `docs/rules/agents.md` (recommended), or use the `executing-plans` skill for inline batch execution. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** [One sentence describing what this builds]
-
-**Architecture:** [2-3 sentences about approach]
-
-**Tech Stack:** [Key technologies/libraries]
-
----
-```
-
-## Task Structure
-
-````markdown
-### Task N: [Component Name]
-
-**Files:**
-- Create: `exact/path/to/file.py`
-- Modify: `exact/path/to/existing.py:123-145`
-- Test: `tests/exact/path/to/test.py`
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-def test_specific_behavior():
-    result = function(input)
-    assert result == expected
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `pytest tests/path/test.py::test_name -v`
-Expected: FAIL with "function not defined"
-
-- [ ] **Step 3: Write minimal implementation**
-
-```python
-def function(input):
-    return expected
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `pytest tests/path/test.py::test_name -v`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add tests/path/test.py src/path/file.py
-git commit -m "feat: add specific feature"
-```
-````
-
-## No Placeholders
-
-Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:
-- "TBD", "TODO", "implement later", "fill in details"
-- "Add appropriate error handling" / "add validation" / "handle edge cases"
-- "Write tests for the above" (without actual test code)
-- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
-- Steps that describe what to do without showing how (code blocks required for code steps)
-- References to types, functions, or methods not defined in any task
-
-## Remember
-- Exact file paths always
-- Complete code in every step — if a step changes code, show the code
-- Exact commands with expected output
-- DRY, YAGNI, TDD, frequent commits
-
-## Self-Review
-
-After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.
-
-**1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.
-
-**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.
-
-**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.
-
-If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.
-
-## Execution Handoff
-
-After saving the plan, offer execution choice:
-
-**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
-
-**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
-
-**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
-
-**Which approach?"**
-
-**If Subagent-Driven chosen:**
-- Dispatch subagents per `docs/rules/agents.md` (fresh subagent per task + two-stage review by `code-reviewer`)
-
-**If Inline Execution chosen:**
-- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
-- Batch execution with checkpoints for review

package/skills/writing-plans/plan-document-reviewer-prompt.md

@@ -1,49 +0,0 @@
-# Plan Document Reviewer Prompt Template
-
-Use this template when dispatching a plan document reviewer subagent.
-
-**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition.
-
-**Dispatch after:** The complete plan is written.
-
-```
-Task tool (general-purpose):
-  description: "Review plan document"
-  prompt: |
-    You are a plan document reviewer. Verify this plan is complete and ready for implementation.
-
-    **Plan to review:** [PLAN_FILE_PATH]
-    **Spec for reference:** [SPEC_FILE_PATH]
-
-    ## What to Check
-
-    | Category | What to Look For |
-    |----------|------------------|
-    | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
-    | Spec Alignment | Plan covers spec requirements, no major scope creep |
-    | Task Decomposition | Tasks have clear boundaries, steps are actionable |
-    | Buildability | Could an engineer follow this plan without getting stuck? |
-
-    ## Calibration
-
-    **Only flag issues that would cause real problems during implementation.**
-    An implementer building the wrong thing or getting stuck is an issue.
-    Minor wording, stylistic preferences, and "nice to have" suggestions are not.
-
-    Approve unless there are serious gaps — missing requirements from the spec,
-    contradictory steps, placeholder content, or tasks so vague they can't be acted on.
-
-    ## Output Format
-
-    ## Plan Review
-
-    **Status:** Approved | Issues Found
-
-    **Issues (if any):**
-    - [Task X, Step Y]: [specific issue] - [why it matters for implementation]
-
-    **Recommendations (advisory, do not block approval):**
-    - [suggestions for improvement]
-```
-
-**Reviewer returns:** Status, Issues (if any), Recommendations