@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/skills/shared/external/monorepo-architect/SKILL.md

@@ -1,63 +1,166 @@
 ---
 name: monorepo-architect
-description: "Expert in monorepo architecture, build systems, and dependency management at scale. Masters Nx, Turborepo, Bazel, and Lerna for efficient multi-project development. Use PROACTIVELY for monorepo setup,. Use when a monorepo's build system, task graph or dependency layout needs designing or fixing."
-risk: safe
-source: community
-date_added: "2026-02-27"
+description: "Monorepo structure: pnpm workspaces, Turborepo or Nx task graphs, affected-only CI, remote cache, package boundaries, Changesets, CODEOWNERS. Use when setting up, migrating to or speeding up a monorepo."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
-# Monorepo Architect
+# Monorepo Architecture
 
-Expert in monorepo architecture, build systems, and dependency management at scale. Masters Nx, Turborepo, Bazel, and Lerna for efficient multi-project development. Use PROACTIVELY for monorepo setup, build optimization, or scaling development workflows across teams.
+A monorepo pays off when changes regularly cross project lines: one commit can
+update a shared library and every consumer, and one CI run proves they still
+agree. It costs build time and coordination unless the tooling only does work
+for what changed. This skill is about keeping that trade favourable.
 
-## Do not use this skill when
+Gradle multi-project builds are covered by `gradle-kotlin-dsl`; Swift packages
+by the iOS build skills. The ideas below transfer, the commands do not.
 
-- The task is unrelated to monorepo architect
-- You need a different domain or tool outside this scope
+## Decide first
 
-## Instructions
+| Question | If yes | If no |
+|----------|--------|-------|
+| Do most changes touch more than one project? | monorepo helps | separate repos may be simpler |
+| Do projects share a language and toolchain? | one workspace tool fits | expect a polyglot tool (Bazel, Pants) or per-area tooling |
+| Must parts be released on independent schedules? | plan versioning per package | a single version is fine |
+| Are access rules per project strict (legal, vendor)? | monorepo is harder | no issue |
 
-- Clarify goals, constraints, and required inputs.
-- Apply relevant best practices and validate outcomes.
-- Provide actionable steps and verification.
+## Layout
 
-## Capabilities
+```
+.
+├── apps/
+│   ├── storefront/        # deployable web app
+│   └── orders-api/        # deployable service
+├── packages/
+│   ├── ui/                # shared components, internal
+│   ├── money/             # published library
+│   └── config-eslint/     # shared tool config
+├── tooling/               # generators, scripts
+├── pnpm-workspace.yaml
+├── turbo.json             # or nx.json
+└── package.json           # root: dev tooling only, private
+```
 
-- Monorepo tool selection (Nx, Turborepo, Bazel, Lerna)
-- Workspace configuration and project structure
-- Build caching (local and remote)
-- Dependency graph management
-- Affected/changed detection for CI optimization
-- Code sharing and library extraction
-- Task orchestration and parallelization
+- `apps/` are leaves: nothing depends on an app.
+- `packages/` are libraries; each has one clear owner and purpose.
+- The root `package.json` is `"private": true` and holds tools, not runtime
+  dependencies.
 
-## Use this skill when
+## Workspaces
 
-- Setting up a new monorepo from scratch
-- Migrating from polyrepo to monorepo
-- Optimizing slow CI/CD pipelines
-- Sharing code between multiple applications
-- Managing dependencies across projects
-- Implementing consistent tooling across teams
+pnpm is the usual choice: strict `node_modules` (no phantom dependencies),
+content-addressed store, fast installs.
 
-## Workflow
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - "apps/*"
+  - "packages/*"
+catalog:
+  typescript: ^5.6.0
+  zod: ^3.23.0
+```
 
-1. Assess codebase size and team structure
-2. Select appropriate monorepo tooling
-3. Design workspace and project structure
-4. Configure build caching strategy
-5. Set up affected/changed detection
-6. Implement task pipelines
-7. Configure remote caching for CI
-8. Document conventions and workflows
+```json
+{
+  "name": "@shop/storefront",
+  "private": true,
+  "dependencies": {
+    "@shop/ui": "workspace:*",
+    "@shop/money": "workspace:^",
+    "zod": "catalog:"
+  }
+}
+```
 
-## Best Practices
+- `workspace:` links the local package; on publish pnpm rewrites it to a real
+  version range.
+- `catalog:` keeps one version of a shared third-party dependency across the
+  repo. npm and Yarn workspaces work too; npm lacks catalogs, so use a lint rule
+  (syncpack, `manypkg`) to keep versions aligned.
+- Commit one lockfile at the root. CI installs with `--frozen-lockfile`.
 
-- Start with clear project boundaries
-- Use consistent naming conventions
-- Implement remote caching early
-- Keep shared libraries focused
-- Use tags for dependency constraints
-- Automate dependency updates
-- Document the dependency graph
-- Set up code ownership rules
+## Affected-only CI
+
+Run tasks only for projects changed since the merge base and their dependents.
+
+```bash
+# Turborepo
+pnpm turbo run lint test build --filter="...[origin/main]"
+
+# Nx
+pnpm nx affected -t lint test build --base=origin/main --head=HEAD
+```
+
+- Check out enough history for the merge base (`fetch-depth: 0` or a fetch of
+  the base branch).
+- Changes to root files (lockfile, root tsconfig, CI config) should mark
+  everything affected; both tools do this when those files are declared as
+  global inputs.
+- Keep a nightly full run to catch anything the graph missed.
+
+## Remote cache
+
+A shared cache lets CI and developers reuse each other's task results.
+
+- Turborepo: Vercel Remote Cache or a self-hosted server implementing the API
+  (`TURBO_API`, `TURBO_TOKEN`, `TURBO_TEAM`).
+- Nx: Nx Cloud, or a self-hosted cache package.
+- CI writes, developers read; restrict write tokens to protected branches so a
+  malicious branch cannot poison artifacts.
+
+## Boundaries
+
+Without enforcement, every package slowly imports every other one and the
+graph turns into a single blob that always rebuilds.
+
+- Tag projects by type and scope (`type:app`, `type:ui`, `type:data`,
+  `scope:orders`, `scope:catalog`) and allow only certain edges. Nx enforces
+  this with the `@nx/enforce-module-boundaries` ESLint rule; in a Turborepo
+  setup use `eslint-plugin-boundaries` or dependency-cruiser.
+- Import packages only through their public entry (`exports` in
+  `package.json`), never `@shop/ui/src/internal/...`.
+- No cycles. Break one by extracting the shared piece into a lower package.
+- TypeScript project references (`composite: true`, `references`) give
+  incremental type checking that follows the same graph.
+
+## Internal versus published packages
+
+| Kind | Build | Version |
+|------|-------|---------|
+| Internal, source-consumed | none; consumers compile its TypeScript directly via `exports` pointing at `src` | `0.0.0`, `private: true` |
+| Internal, prebuilt | builds to `dist`, cached | `private: true` |
+| Published | builds to `dist`, typed exports, changelog | semver via Changesets |
+
+Source-consumed internal packages are the simplest start; switch a package to
+prebuilt when its consumers' build times grow.
+
+## Ownership
+
+```
+# .github/CODEOWNERS
+/apps/storefront/        @shop/web-team
+/apps/orders-api/        @shop/orders-team
+/packages/money/         @shop/platform-team
+/pnpm-workspace.yaml     @shop/platform-team
+/.github/                @shop/platform-team
+```
+
+Pair CODEOWNERS with branch protection that requires owner review, so a change
+to a shared package cannot merge without its owners.
+
+## Symptoms and fixes
+
+| Symptom | Likely cause |
+|---------|--------------|
+| Every PR rebuilds everything | a root file declared as global input changes often, or an app is depended on |
+| Cache hits produce wrong output | undeclared env var or file input |
+| "Module not found" only in CI | phantom dependency hoisted locally; add it to the package's own `dependencies` |
+| Two copies of a library at runtime | version drift; use a catalog or align ranges |
+| Release publishes unexpected packages | missing `private: true` on an internal package |
+
+## References
+
+- `references/patterns.md`: Turborepo/Nx task graph and cache inputs, Changesets release flow, and moving existing repos in with history. Load it when the task reaches those topics.

package/pipeline/skills/shared/external/monorepo-architect/references/patterns.md

@@ -0,0 +1,70 @@
+# Monorepo patterns
+
+Loaded on demand from `../SKILL.md`.
+
+## Task graph
+
+The build tool needs to know, for each task, what it depends on, what inputs
+change its result, and what outputs it produces. With that, it can order work,
+run independent tasks in parallel and skip tasks whose inputs did not change.
+
+Turborepo:
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": ["src/**", "package.json", "tsconfig.json"],
+      "outputs": ["dist/**"]
+    },
+    "test": {
+      "dependsOn": ["^build"],
+      "inputs": ["src/**", "test/**"],
+      "outputs": ["coverage/**"]
+    },
+    "lint": {},
+    "dev": { "cache": false, "persistent": true }
+  }
+}
+```
+
+`^build` means "build my dependencies first". Nx expresses the same with
+`targetDefaults` and `namedInputs` in `nx.json`, and can infer targets from
+tool config files.
+
+Rules that keep caching correct:
+
+- Declare every input that changes output, including env vars
+  (`env` in Turborepo, `{env.X}` inputs in Nx). An undeclared input gives stale
+  cache hits.
+- Declare outputs precisely; a missing output is not restored on a hit.
+- Tasks must be deterministic: no timestamps or absolute paths in artifacts.
+
+## Versioning and release with Changesets
+
+```bash
+pnpm changeset          # author picks packages and bump type, writes a note
+pnpm changeset version  # applies bumps, updates changelogs and dependents
+pnpm changeset publish  # publishes what changed, tags releases
+```
+
+- Each PR that changes a published package includes a changeset file; a CI
+  check fails when one is missing.
+- The Changesets GitHub action opens a "Version Packages" PR; merging it
+  publishes.
+- `fixed` groups keep packages on one shared version; `linked` bumps them
+  together only when released together.
+- Apps are not versioned by Changesets; they deploy by commit.
+
+## Migrating repos in
+
+1. Import each repo with history into its target folder (`git subtree add` or
+   `git filter-repo --to-subdirectory-filter`), one at a time.
+2. Align toolchain versions (Node, TypeScript, lint config) before merging
+   dependency trees.
+3. Replace published-version dependencies between the imported projects with
+   `workspace:` links.
+4. Add the task graph and affected CI before the third project arrives, not
+   after CI times double.

package/pipeline/skills/shared/external/musickit-audio/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: musickit-audio
 description: "Integrate Apple Music playback, catalog search, and Now Playing metadata using MusicKit and MediaPlayer. Use when adding music search, Apple Music subscription flows, queue management, playback controls, remote command handling, or Now Playing info to iOS apps."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # MusicKit

package/pipeline/skills/shared/external/musickit-audio/evals/evals.json

@@ -1,5 +1,5 @@
 {
-  "skill_name": "musickit",
+  "skill_name": "musickit-audio",
   "evals": [
     {
       "id": 1,

package/pipeline/skills/shared/external/natural-language/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: natural-language
 description: "Tokenize, tag, and analyze natural language text using Apple's NaturalLanguage framework and translate between languages with the Translation framework. Use when adding language identification, sentiment analysis, named entity recognition, part-of-speech tagging, text embeddings, or in-app translation to iOS/macOS/visionOS apps."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # NaturalLanguage + Translation

package/pipeline/skills/shared/external/nextjs-app-router/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: nextjs-app-router
 description: "Next.js 15+ App Router: Server/Client Components, Server Actions, data fetching, layouts, middleware, ISR/SSG/SSR, and routing patterns. Use when building or reviewing App Router work: Server Components, Server Actions, data fetching, layouts."
-tags: [nextjs, react, frontend, ssr, app-router, full-stack]
-version: "2025.1"
+metadata:
+  tags: [nextjs, react, frontend, ssr, app-router, full-stack]
+  version: "2025.1"
 ---
 
 # Next.js 15+ App Router

package/pipeline/skills/shared/external/nodejs-backend-patterns/SKILL.md

@@ -1,34 +1,104 @@
 ---
 name: nodejs-backend-patterns
-description: "Comprehensive guidance for building scalable, maintainable, and production-ready Node.js backend applications with modern frameworks, architectural patterns, and best practices. Use when building or reviewing a Node.js service: structure, error handling, configuration, scaling."
-risk: safe
-source: community
-date_added: "2026-02-27"
+description: "Node.js 22/24 services in ESM: structure, validated config, error mapping, graceful shutdown, AsyncLocalStorage, streams, queues, node:test. Use when building or reviewing a Node.js backend."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
 # Node.js Backend Patterns
 
-Comprehensive guidance for building scalable, maintainable, and production-ready Node.js backend applications with modern frameworks, architectural patterns, and best practices.
+A Node service fails in a few characteristic ways: one blocking call stalls every
+request, a forgotten `await` loses an error, a deploy kills requests mid-way,
+or a missing environment variable surfaces as `undefined` three layers deep at
+2 a.m. The patterns below exist to make those failures impossible or loud.
 
-## Use this skill when
+Assumes Node 22 or 24 LTS and ES modules. Type-level guidance lives in
+`typescript-patterns`; schema and query work in `database-patterns`; test
+strategy beyond the runner in `testing-backend`.
 
-- Building REST APIs or GraphQL servers
-- Creating microservices with Node.js
-- Implementing authentication and authorization
-- Designing scalable backend architectures
-- Setting up middleware and error handling
-- Integrating databases (SQL and NoSQL)
-- Building real-time applications with WebSockets
-- Implementing background job processing
+## 1. Core rules
 
-## Do not use this skill when
+Load `references/runtime-patterns.md` for the full code. The rules it implements:
 
-- The task is unrelated to node.js backend patterns
-- You need a different domain or tool outside this scope
+- **Project shape**: group by feature, keep HTTP at the edge, and build the
+  server from a side-effect-free `buildApp(config, deps)` factory; `main.ts`
+  only loads config, builds, listens and handles signals.
+- **Configuration**: parse `process.env` once with a schema (zod), freeze the
+  result, exit on invalid input, and pass `config` down; no `process.env` reads
+  elsewhere and no committed `.env` secrets.
+- **Errors**: expected failures throw a typed `AppError` (stable code, HTTP
+  status); unexpected ones reach one error handler that returns RFC 9457 problem
+  details without leaking internals. Crash on `uncaughtException` and
+  `unhandledRejection` and let the orchestrator restart. Lint with
+  `no-floating-promises` and `no-misused-promises`.
+- **Graceful shutdown**: on `SIGTERM`, fail readiness, stop accepting work,
+  finish in-progress requests and jobs, close pools, exit within a bounded
+  grace period. Liveness stays cheap and never touches dependencies.
+- **Request context**: `AsyncLocalStorage` carries request id and principal for
+  logging and tracing; business inputs stay explicit parameters.
+- **Timeouts**: every outbound call gets `AbortSignal.timeout` (combined with
+  the request's signal via `AbortSignal.any`); set statement, pool-acquire and
+  server timeouts.
+- **Streams**: stream large payloads through `stream/promises` `pipeline`,
+  which propagates errors and destroys every stage; avoid manual `.pipe()`.
 
-## Instructions
+## 2. Keep the event loop free
 
-- Clarify goals, constraints, and required inputs.
-- Apply relevant best practices and validate outcomes.
-- Provide actionable steps and verification.
+One thread runs all JavaScript. Anything CPU-heavy or synchronous blocks every
+request.
 
+- Never use `*Sync` fs or crypto calls in request paths.
+- Large `JSON.parse`/`JSON.stringify`, image processing, PDF rendering,
+  compression of big payloads, and bcrypt/argon2 with high cost go to worker
+  threads (`node:worker_threads`, or a pool like `piscina`) or a separate job.
+- Monitor loop delay with `perf_hooks.monitorEventLoopDelay()` and export it as
+  a metric; a p99 above ~100 ms means something is blocking.
+
+## 3. Background work
+
+- Anything that can fail independently of the response (emails, webhooks,
+  thumbnails, third-party sync) goes on a durable queue: BullMQ on Redis,
+  pg-boss on Postgres, or a cloud queue (SQS, Pub/Sub).
+- Jobs must be idempotent and carry an id; queues deliver at least once.
+- Configure retries with exponential backoff and a dead-letter destination.
+- Write the domain change and the "job to enqueue" record in one transaction
+  (outbox pattern) when losing the job would be a bug.
+- Run workers as a separate process type from the HTTP server so they scale and
+  deploy independently.
+
+## 4. Testing and framework choice
+
+Tests build the app from `buildApp(config, fakeDeps())` and call it in memory
+(`app.inject()` on Fastify, `supertest` on Express) with the built-in
+`node:test` runner. Worked examples, runner flags and a comparison of Fastify,
+Express 5, NestJS and Hono, plus logging and observability defaults (pino,
+redaction, OpenTelemetry), are in `references/testing-and-frameworks.md`.
+
+## Review checklist
+
+- [ ] Config parsed and validated once at startup; no scattered `process.env`.
+- [ ] No floating promises; one central error handler returning problem details.
+- [ ] `SIGTERM` drains requests, jobs and pools within a bounded grace period.
+- [ ] Readiness and liveness are separate; liveness does not touch dependencies.
+- [ ] Every outbound call and query has a timeout.
+- [ ] No synchronous or CPU-heavy work on request paths.
+- [ ] Large payloads stream through `pipeline`.
+- [ ] Side effects that may fail run as idempotent queued jobs.
+- [ ] Logs are structured, correlated by request id, and redact secrets.
+- [ ] Tests build the app from a factory with injected dependencies.
+
+## References
+
+- `references/runtime-patterns.md`: layout, config, errors, shutdown, request context, timeouts and streams in full.
+- `references/testing-and-frameworks.md`: `node:test` examples, framework comparison, logging and OpenTelemetry defaults.
+
+## Related skills
+
+- `api-patterns`, `rest-api-design`: the contract this service implements.
+- `api-security-best-practices`: authentication, authorization, rate limits.
+- `typescript-patterns`: types, Zod, strict mode.
+- `database-patterns`: schema, migrations, query tuning.
+- `testing-backend`: test pyramid and fixtures.
+- `docker-expert`, `observability-engineer`: packaging and running it.