@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.0

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

@@ -19,275 +19,15 @@ for all pipeline definitions.
 
 ### 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
-```
+Code for this section: [CI/CD pipeline examples](references/pipeline-examples.md).
 
 ### 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"
-```
+Code for this section: [CI/CD pipeline examples](references/pipeline-examples.md).
 
 ## 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"]
-```
+Code for this section: [CI/CD pipeline examples](references/pipeline-examples.md).
 
 ## Environment Management
 
@@ -463,3 +203,7 @@ async function handleRequest(req: Request) {
 | 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 |
+
+## References
+
+- [CI/CD pipeline examples](references/pipeline-examples.md): open when writing a full CI workflow, a deploy workflow or a multi-stage Docker build.

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

@@ -0,0 +1,281 @@
+# CI/CD pipeline examples
+
+<!-- toc -->
+- [Full CI Pipeline](#full-ci-pipeline)
+- [Deploy Workflow](#deploy-workflow)
+- [Docker Multi-Stage Builds](#docker-multi-stage-builds)
+<!-- /toc -->
+
+Complete GitHub Actions CI and deploy workflows and a multi-stage Dockerfile. SKILL.md keeps the principles, environment and secret rules, and deployment strategies.
+
+## 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"]
+```

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

@@ -46,15 +46,7 @@ a tidy body behind a misleading name, because callers only ever see the name.
 - Length follows scope: `i` is fine in a three-line loop; a module-level value
   needs a full phrase.
 
-```python
-# Before
-def calc(d, f):
-    return d * (1 - f)
-
-# After
-def discounted_price(list_price: Decimal, discount_rate: Decimal) -> Decimal:
-    return list_price * (1 - discount_rate)
-```
+Code: [1. Names](references/code-examples.md#1-names).
 
 ## 2. Units of work
 
@@ -66,14 +58,7 @@ def discounted_price(list_price: Decimal, discount_rate: Decimal) -> Decimal:
   usually means a missing type or two functions sharing a name.
 - A body longer than a screen is a prompt to look for the seams, not a rule.
 
-```swift
-// Before: the flag hides two behaviours
-func export(_ report: Report, asPDF: Bool) -> Data
-
-// After: two names, no flag
-func exportPDF(_ report: Report) -> Data
-func exportCSV(_ report: Report) -> Data
-```
+Code: [2. Units of work](references/code-examples.md#2-units-of-work).
 
 ## 3. Control flow
 
@@ -85,23 +70,7 @@ func exportCSV(_ report: Report) -> Data
   better than the raw expression inside an `if`.
 - Nesting past two levels almost always hides a function waiting to be extracted.
 
-```typescript
-// Before
-function shippingCost(order: Order): number {
-  if (order.items.length > 0) {
-    if (!order.isDigital) {
-      return order.weightKg * RATE_PER_KG;
-    }
-  }
-  return 0;
-}
-
-// After
-function shippingCost(order: Order): number {
-  if (order.items.length === 0 || order.isDigital) return 0;
-  return order.weightKg * RATE_PER_KG;
-}
-```
+Code: [3. Control flow](references/code-examples.md#3-control-flow).
 
 ## 4. State and side effects
 
@@ -124,13 +93,7 @@ function shippingCost(order: Order): number {
 - Check the boundaries every time: empty input, one element, the maximum, and
   values that are present but invalid.
 
-```kotlin
-// Before: the caller cannot tell "not found" from "zero"
-fun itemCount(orderId: String): Int = repository.find(orderId)?.items ?: 0
-
-// After
-fun itemCount(orderId: String): Int? = repository.find(orderId)?.items
-```
+Code: [5. Errors and edge values](references/code-examples.md#5-errors-and-edge-values).
 
 ## 6. Comments
 
@@ -194,3 +157,7 @@ Leave formatting to the formatter and say nothing about it.
 - Speed and memory: profile first, then use the stack's performance skill.
 - Module boundaries and system design: use `architecture`.
 - Language style rules a linter enforces: follow the linter.
+
+## References
+
+- [Code examples](references/code-examples.md): open for the full code behind 1. Names, 2. Units of work, 3. Control flow, 5. Errors and edge values.

package/pipeline/skills/shared/external/clean-code/references/code-examples.md

@@ -0,0 +1,56 @@
+# Clean Code Code Examples
+
+Full code samples for the SKILL.md sections that link here. The rules and the decision guidance stay in SKILL.md; each heading below matches the SKILL.md section the code belongs to.
+
+## 1. Names
+
+```python
+# Before
+def calc(d, f):
+    return d * (1 - f)
+
+# After
+def discounted_price(list_price: Decimal, discount_rate: Decimal) -> Decimal:
+    return list_price * (1 - discount_rate)
+```
+
+## 2. Units of work
+
+```swift
+// Before: the flag hides two behaviours
+func export(_ report: Report, asPDF: Bool) -> Data
+
+// After: two names, no flag
+func exportPDF(_ report: Report) -> Data
+func exportCSV(_ report: Report) -> Data
+```
+
+## 3. Control flow
+
+```typescript
+// Before
+function shippingCost(order: Order): number {
+  if (order.items.length > 0) {
+    if (!order.isDigital) {
+      return order.weightKg * RATE_PER_KG;
+    }
+  }
+  return 0;
+}
+
+// After
+function shippingCost(order: Order): number {
+  if (order.items.length === 0 || order.isDigital) return 0;
+  return order.weightKg * RATE_PER_KG;
+}
+```
+
+## 5. Errors and edge values
+
+```kotlin
+// Before: the caller cannot tell "not found" from "zero"
+fun itemCount(orderId: String): Int = repository.find(orderId)?.items ?: 0
+
+// After
+fun itemCount(orderId: String): Int? = repository.find(orderId)?.items
+```