@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/ci-cd-pipelines/SKILL.md

@@ -0,0 +1,462 @@
+---
+description: "CI/CD pipelines: GitHub Actions workflows, Docker multi-stage builds, environment management, secret management, deployment strategies"
+tags: [ci-cd, github-actions, docker, deployment, devops, backend]
+version: "2025.1"
+---
+
+# CI/CD Pipelines
+
+## Core Principles
+
+CI/CD pipelines should be fast, reliable, and reproducible. Every push should trigger
+automated testing. Every merge to main should be deployable. Use infrastructure as code
+for all pipeline definitions.
+
+## GitHub Actions Workflows
+
+### Full CI Pipeline
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: '22'
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check
+        run: npm run type-check
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: test_db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Run migrations
+        run: npx prisma migrate deploy
+        env:
+          DATABASE_URL: postgresql://test:test@localhost:5432/test_db
+
+      - name: Run tests
+        run: npm test -- --coverage
+        env:
+          DATABASE_URL: postgresql://test:test@localhost:5432/test_db
+          REDIS_URL: redis://localhost:6379
+
+      - name: Upload coverage
+        if: github.event_name == 'pull_request'
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  e2e:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run E2E tests
+        run: npx playwright test
+        env:
+          BASE_URL: http://localhost:3000
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, e2e]
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=sha
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+### Deploy Workflow
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+
+jobs:
+  deploy-staging:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    environment: staging
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy to staging
+        run: |
+          echo "Deploying to staging..."
+          # Use your deployment tool
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+          DEPLOY_URL: ${{ vars.STAGING_URL }}
+
+      - name: Run smoke tests
+        run: |
+          curl --fail --retry 5 --retry-delay 10 "${{ vars.STAGING_URL }}/health"
+
+  deploy-production:
+    needs: deploy-staging
+    runs-on: ubuntu-latest
+    environment: production
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy to production
+        run: |
+          echo "Deploying to production..."
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+          DEPLOY_URL: ${{ vars.PRODUCTION_URL }}
+
+      - name: Verify deployment
+        run: |
+          curl --fail --retry 5 --retry-delay 10 "${{ vars.PRODUCTION_URL }}/health"
+```
+
+## Docker Multi-Stage Builds
+
+```dockerfile
+# Dockerfile
+# Stage 1: Dependencies
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --production=false
+
+# Stage 2: Build
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+RUN npm prune --production
+
+# Stage 3: Production
+FROM node:22-alpine AS runner
+WORKDIR /app
+
+# Security: non-root user
+RUN addgroup --system app && adduser --system --ingroup app app
+
+# Copy only what's needed
+COPY --from=builder --chown=app:app /app/dist ./dist
+COPY --from=builder --chown=app:app /app/node_modules ./node_modules
+COPY --from=builder --chown=app:app /app/package.json ./
+
+USER app
+EXPOSE 3000
+
+ENV NODE_ENV=production
+ENV PORT=3000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
+CMD ["node", "dist/server.js"]
+```
+
+```dockerfile
+# Python multi-stage
+FROM python:3.12-slim AS builder
+WORKDIR /app
+RUN pip install --no-cache-dir poetry
+COPY pyproject.toml poetry.lock ./
+RUN poetry export -f requirements.txt -o requirements.txt --without-hashes
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+FROM python:3.12-slim AS runner
+WORKDIR /app
+RUN useradd --system app
+COPY --from=builder /install /usr/local
+COPY . .
+USER app
+EXPOSE 8000
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+## Environment Management
+
+```yaml
+# .github/workflows/deploy.yml — environment protection rules
+# Configure in GitHub Settings > Environments:
+# - staging: auto-deploy on main push
+# - production: require manual approval + 2 reviewers
+
+jobs:
+  deploy-production:
+    environment:
+      name: production
+      url: https://myapp.com
+```
+
+```bash
+# .env.example (committed — template only)
+DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
+REDIS_URL=redis://localhost:6379
+API_KEY=your-api-key-here
+JWT_SECRET=your-jwt-secret-here
+
+# .env.local (gitignored — local development)
+# .env.staging (managed via CI secrets)
+# .env.production (managed via CI secrets)
+```
+
+```typescript
+// config.ts — typed environment configuration
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  API_KEY: z.string().min(1),
+});
+
+export const env = EnvSchema.parse(process.env);
+```
+
+## Secret Management
+
+```yaml
+# GitHub Actions secrets
+# Settings > Secrets and variables > Actions
+
+# Repository secrets (available to all workflows)
+# DEPLOY_TOKEN, DATABASE_URL, API_KEY
+
+# Environment secrets (scoped to environment)
+# production/DATABASE_URL, production/API_KEY
+
+# Usage in workflow
+steps:
+  - name: Deploy
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      API_KEY: ${{ secrets.API_KEY }}
+    run: ./deploy.sh
+```
+
+```yaml
+# NEVER do this:
+env:
+  API_KEY: "sk-hardcoded-secret-123"  # FORBIDDEN
+
+# NEVER echo secrets in logs:
+- run: echo ${{ secrets.API_KEY }}  # FORBIDDEN — visible in logs
+
+# Safe pattern:
+- run: |
+    if [ -z "$API_KEY" ]; then
+      echo "::error::API_KEY is not set"
+      exit 1
+    fi
+    echo "API key is configured (length: ${#API_KEY})"
+  env:
+    API_KEY: ${{ secrets.API_KEY }}
+```
+
+## Deployment Strategies
+
+### Blue-Green Deployment
+
+```
+1. Blue (current production) serves traffic
+2. Deploy new version to Green environment
+3. Run health checks and smoke tests on Green
+4. Switch load balancer to point to Green
+5. Keep Blue as rollback target
+6. If issues: switch back to Blue instantly
+```
+
+### Canary Deployment
+
+```
+1. Deploy new version to small percentage of servers (5-10%)
+2. Monitor error rates, latency, and key metrics
+3. If healthy after observation window:
+   - Gradually increase traffic (25%, 50%, 100%)
+4. If unhealthy:
+   - Route all traffic back to stable version
+   - Investigate and fix
+```
+
+### Rolling Deployment
+
+```yaml
+# Kubernetes rolling update
+apiVersion: apps/v1
+kind: Deployment
+spec:
+  replicas: 4
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1          # 1 extra pod during update
+      maxUnavailable: 0    # Never reduce available pods
+```
+
+### Feature Flags
+
+```typescript
+// Use feature flags for gradual rollout
+import { getFeatureFlag } from '@/lib/feature-flags';
+
+async function handleRequest(req: Request) {
+  const useNewAlgorithm = await getFeatureFlag('new-search-algorithm', {
+    userId: req.userId,
+    percentage: 10, // 10% rollout
+  });
+
+  if (useNewAlgorithm) {
+    return newSearchAlgorithm(req.query);
+  }
+  return legacySearchAlgorithm(req.query);
+}
+```
+
+## Do's
+
+- Run lint and type checking before tests (fail fast)
+- Use service containers for database/cache in CI tests
+- Cache dependencies (npm, pip) between CI runs
+- Use multi-stage Docker builds to minimize image size
+- Run security scanning (Dependabot, Snyk) on every PR
+- Use GitHub Environments with protection rules for production
+- Include health check endpoints in every service
+- Validate environment variables at startup with schema validation
+
+## Don'ts
+
+- Do not hardcode secrets in workflow files, Dockerfiles, or source code
+- Do not use `latest` tags for Docker base images — pin specific versions
+- Do not skip tests for "quick" deployments
+- Do not deploy directly to production without staging verification
+- Do not store `.env` files in version control
+- Do not run containers as root in production
+- Do not use `docker-compose` for production deployments
+- Do not ignore failing health checks during deployment
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| CI is slow | No caching, sequential jobs | Add dependency caching, parallelize independent jobs |
+| Flaky CI tests | Timing issues, shared state | Add retries for infrastructure, isolate test state |
+| Docker build fails | Layer cache invalidated | Order Dockerfile: deps first, code last |
+| Secret not available | Wrong scope or missing secret | Check repository vs environment secrets; verify name |
+| Deploy succeeds but app crashes | Missing env vars in production | Validate env at startup, check deployment config |
+| Rollback needed | Bad deploy passed health checks | Improve health checks, add smoke tests, use canary |

package/pipeline/skills/shared/external/clean-code/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: clean-code
+description: "This skill embodies the principles of \"Clean Code\" by Robert C. Martin (Uncle Bob). Use it to transform \"code that works\" into \"code that is clean.\""
+risk: safe
+source: "ClawForge (https://github.com/jackjin1997/ClawForge)"
+date_added: "2026-02-27"
+---
+
+# Clean Code Skill
+
+This skill embodies the principles of "Clean Code" by Robert C. Martin (Uncle Bob). Use it to transform "code that works" into "code that is clean."
+
+## 🧠 Core Philosophy
+> "Code is clean if it can be read, and enhanced by a developer other than its original author." — Grady Booch
+
+## When to Use
+Use this skill when:
+- **Writing new code**: To ensure high quality from the start.
+- **Reviewing Pull Requests**: To provide constructive, principle-based feedback.
+- **Refactoring legacy code**: To identify and remove code smells.
+- **Improving team standards**: To align on industry-standard best practices.
+
+## 1. Meaningful Names
+- **Use Intention-Revealing Names**: `elapsedTimeInDays` instead of `d`.
+- **Avoid Disinformation**: Don't use `accountList` if it's actually a `Map`.
+- **Make Meaningful Distinctions**: Avoid `ProductData` vs `ProductInfo`.
+- **Use Pronounceable/Searchable Names**: Avoid `genymdhms`.
+- **Class Names**: Use nouns (`Customer`, `WikiPage`). Avoid `Manager`, `Data`.
+- **Method Names**: Use verbs (`postPayment`, `deletePage`).
+
+## 2. Functions
+- **Small!**: Functions should be shorter than you think.
+- **Do One Thing**: A function should do only one thing, and do it well.
+- **One Level of Abstraction**: Don't mix high-level business logic with low-level details (like regex).
+- **Descriptive Names**: `isPasswordValid` is better than `check`.
+- **Arguments**: 0 is ideal, 1-2 is okay, 3+ requires a very strong justification.
+- **No Side Effects**: Functions shouldn't secretly change global state.
+
+## 3. Comments
+- **Don't Comment Bad Code—Rewrite It**: Most comments are a sign of failure to express ourselves in code.
+- **Explain Yourself in Code**: 
+  ```python
+  # Check if employee is eligible for full benefits
+  if employee.flags & HOURLY and employee.age > 65:
+  ```
+  vs
+  ```python
+  if employee.isEligibleForFullBenefits():
+  ```
+- **Good Comments**: Legal, Informative (regex intent), Clarification (external libraries), TODOs.
+- **Bad Comments**: Mumbling, Redundant, Misleading, Mandated, Noise, Position Markers.
+
+## 4. Formatting
+- **The Newspaper Metaphor**: High-level concepts at the top, details at the bottom.
+- **Vertical Density**: Related lines should be close to each other.
+- **Distance**: Variables should be declared near their usage.
+- **Indentation**: Essential for structural readability.
+
+## 5. Objects and Data Structures
+- **Data Abstraction**: Hide the implementation behind interfaces.
+- **The Law of Demeter**: A module should not know about the innards of the objects it manipulates. Avoid `a.getB().getC().doSomething()`.
+- **Data Transfer Objects (DTO)**: Classes with public variables and no functions.
+
+## 6. Error Handling
+- **Use Exceptions instead of Return Codes**: Keeps logic clean.
+- **Write Try-Catch-Finally First**: Defines the scope of the operation.
+- **Don't Return Null**: It forces the caller to check for null every time.
+- **Don't Pass Null**: Leads to `NullPointerException`.
+
+## 7. Unit Tests
+- **The Three Laws of TDD**:
+  1. Don't write production code until you have a failing unit test.
+  2. Don't write more of a unit test than is sufficient to fail.
+  3. Don't write more production code than is sufficient to pass the failing test.
+- **F.I.R.S.T. Principles**: Fast, Independent, Repeatable, Self-Validating, Timely.
+
+## 8. Classes
+- **Small!**: Classes should have a single responsibility (SRP).
+- **The Stepdown Rule**: We want the code to read like a top-down narrative.
+
+## 9. Smells and Heuristics
+- **Rigidity**: Hard to change.
+- **Fragility**: Breaks in many places.
+- **Immobility**: Hard to reuse.
+- **Viscosity**: Hard to do the right thing.
+- **Needless Complexity/Repetition**.
+
+## 🛠️ Implementation Checklist
+- [ ] Is this function smaller than 20 lines?
+- [ ] Does this function do exactly one thing?
+- [ ] Are all names searchable and intention-revealing?
+- [ ] Have I avoided comments by making the code clearer?
+- [ ] Am I passing too many arguments?
+- [ ] Is there a failing test for this change?

package/pipeline/skills/shared/external/closed-loop-delivery/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: closed-loop-delivery
+description: Use when a coding task must be completed against explicit acceptance criteria with minimal user re-intervention across implementation, review feedback, deployment, and runtime verification.
+risk: safe
+source: community
+date_added: "2026-03-12"
+---
+
+# Closed-Loop Delivery
+
+## Overview
+
+Treat each task as incomplete until acceptance criteria are verified in evidence, not until code is merely changed.
+
+Core rule: **deliver against DoD (Definition of Done), not against code diff size.**
+
+## When to Use
+Use this skill when:
+- user gives a coding/fix task and expects end-to-end completion
+- task spans code + tests + PR comments + dev deploy + runtime checks
+- repeated manual prompts like "now test", "now deploy", "now re-check PR" should be avoided
+
+Do not use this skill for:
+- pure Q&A/explanations
+- prod deploy requests without explicit human approval
+- tasks blocked by missing secrets/account access that cannot be inferred
+
+## Required Inputs
+
+Before execution, define these once:
+- task goal
+- acceptance criteria (DoD)
+- target environment (`dev` by default)
+- max iteration rounds (default `2`)
+
+If acceptance criteria are missing, request them once. If user does not provide, propose a concrete default and proceed.
+
+## Issue Gate Dependency
+
+Before execution, prefer using `create-issue-gate`.
+
+- If issue status is `ready` and execution gate is `allowed`, continue.
+- If issue status is `draft`, do not execute implementation/deploy/review loops.
+- Require user-provided, testable acceptance criteria before starting execution.
+
+## Default Workflow
+
+1. **Define DoD**
+   - Convert request into testable criteria.
+   - Example: checkout task DoD = "checkout endpoint returns a valid, openable third-party payment URL in dev".
+
+2. **Implement minimal change**
+   - Keep scope tight to task goal.
+
+3. **Verify locally**
+   - Run focused tests first, then broader checks if needed.
+
+4. **Review loop**
+   - Fetch PR comments/reviews.
+   - Classify valid vs non-actionable.
+   - Fix valid items, re-run verification.
+
+5. **Dev deploy + runtime verification**
+   - Deploy to `dev` when runtime behavior matters.
+   - Verify via real API/Lambda/log evidence against DoD.
+
+6. **Completion decision**
+   - Only report "done" when all DoD checks pass.
+   - Otherwise continue loop until pass or stop condition.
+
+## PR Comment Polling Policy
+
+Avoid noisy short polling by default. Use batched windows:
+
+- **Round 1:** wait `3m`, collect delta comments/reviews
+- **Round 2:** wait `6m`, collect delta again
+- **Final round:** wait `10m`, collect all remaining visible comments/reviews
+
+At each round:
+- process all new comments in one batch
+- avoid immediate re-poll after each single comment
+- after the `10m` round, stop waiting and proceed with all comments visible at that point
+
+If CI is still running, align polling to check completion boundaries instead of fixed rapid polling.
+
+## Human Gate Rules (Must Ask)
+
+Require explicit user confirmation for:
+- production/staging deploy beyond agreed scope
+- destructive operations (history rewrite, force push, data-destructive ops)
+- actions with billing/security posture changes
+- secret values not available in repo/runtime
+- ambiguous DoD that materially changes outcome
+
+## Iteration/Stop Conditions
+
+Stop and escalate with a concise blocker report when:
+- DoD still fails after max rounds (`2` default)
+- external dependency blocks progress (provider outage, missing creds, account permission)
+- conflicting review instructions cannot both be satisfied
+
+Escalation report must include:
+- what passed
+- what failed
+- evidence (commands/logs/API result)
+- smallest decision needed from user
+
+## Output Contract
+
+When claiming completion, always include:
+- acceptance criteria checklist with pass/fail
+- commands/tests run
+- runtime evidence (endpoint/Lambda/log key lines)
+- PR status (new actionable comments count)
+
+Do not claim success without evidence.