Dynamic Pattern Configuration System

Overview

A YAML/JSON-based pattern definition system that allows:

• ✅ Live URL references - LLMs fetch latest documentation at runtime
• ✅ Easy updates - Change URLs without code deployment
• ✅ CI/CD validation - GitHub Actions verify links and rebuild
• ✅ Community contributions - Non-developers can add patterns via YAML
• ✅ Multiple sources - Support multiple authoritative links per pattern
• ✅ Platform agnostic - Add Firebase, AWS, Azure, etc. easily

---

Selecting Quality Authoritative Sources

Why Authoritative Sources Matter

Authoritative sources are the foundation of pattern quality. They're what LLMs query to:

• Generate accurate deployment plans
• Understand platform-specific best practices
• Discover up-to-date configuration options
• Learn troubleshooting steps
• Find production-ready code examples

Poor source selection = poor deployments. Here's how to choose wisely.

URL Type Hierarchy

Tier 1: Priority 10 (Required for Deployment) ⭐⭐⭐

1. Official Framework/Pattern Documentation

- type: 'documentation'
  url: 'https://validatedpatterns.io/'
  purpose: 'Red Hat Validated Patterns - official framework'
  priority: 10
  requiredForDeployment: true

• What: Main documentation hub from the vendor/project
• Why: Source of truth, complete, actively maintained
• Examples: validatedpatterns.io, firebase.google.com/docs, kubernetes.io/docs

2. Interactive Workshops & Hands-On Tutorials

- type: 'documentation'
  url: 'https://play.validatedpatterns.io/vp-workshop/main/index.html'
  purpose: 'Interactive workshop with step-by-step guidance'
  priority: 10
  requiredForDeployment: true

• What: Guided learning experiences, codelabs, workshops
• Why: Step-by-step deployment guidance, troubleshooting tips
• Examples: Katacoda, Google Codelabs, interactive docs

3. Official Code Repositories

- type: 'repository'
  url: 'https://github.com/validatedpatterns/common'
  purpose: 'Common framework code and utilities'
  priority: 10
  requiredForDeployment: true

• What: Official repos with framework code, samples, starters
• Why: Production-ready code, integration patterns, real implementations
• Examples: /validatedpatterns/common, /firebase/functions-samples

Tier 2: Priority 9 (Highly Recommended) ⭐⭐

4. Pattern Collections & Architecture Centers

- type: 'repository'
  url: 'https://github.com/validatedpatterns'
  purpose: 'Collection of all validated pattern repositories'
  priority: 9

• What: Collections of patterns, architecture guidance
• Why: Multiple implementation examples, architectural best practices
• Examples: GitHub org repos, AWS Architecture Center, GCP solutions

5. Getting Started Guides

- type: 'documentation'
  url: 'https://docs.openshift.com/getting-started/'
  purpose: 'Quick start and initial setup'
  priority: 9

• What: Quick start guides, first-deployment tutorials
• Why: Fast onboarding, prerequisites, environment setup
• Examples: "Getting Started", "Quick Start", "First Deployment"

Tier 3: Priority 7-8 (Supplementary) ⭐

6. Developer Tools & CLIs

- type: 'community'
  url: 'https://github.com/openshift/odo'
  purpose: 'Developer CLI for iterative development'
  priority: 7

• What: Developer-focused tools, CLIs, SDKs
• Why: Local development, developer workflow
• Examples: odo, firebase-tools, cloud CLIs

7. Community Resources

- type: 'community'
  url: 'https://stackoverflow.com/questions/tagged/openshift'
  priority: 7

• What: Community forums, Q&A sites
• Why: Real-world problems, community solutions, edge cases

Tier 4: Priority 6 (Foundation)

8. Underlying Technology Documentation

- type: 'specification'
  url: 'https://kubernetes.io/docs/'
  purpose: 'Kubernetes docs (OpenShift builds on k8s)'
  priority: 6

• What: Docs for underlying technologies
• Why: Foundational knowledge
• Examples: Kubernetes (for OpenShift), Node.js (for serverless)

URL Selection Checklist

Before adding a URL, verify:

✅ Accessibility: Publicly accessible (no login wall) ✅ Freshness: Updated within 12 months ✅ Actionable: Contains deployment steps, not just marketing ✅ Official: From vendor/project, not third-party ✅ LLM-Friendly: Text-based content LLMs can parse ✅ Complementary: Adds value, doesn't duplicate ✅ Permanent: Stable URL, not likely to break

URLs to Avoid ❌

Type	Why Avoid	Alternative
Marketing pages	No technical content	Link to docs section instead
Paywalled content	LLMs can't access	Use free tier or public docs
Login-required	LLMs can't authenticate	Link to public docs
Blog posts	Outdated quickly	Use official docs
Third-party tutorials	May be incorrect	Use official tutorials
Video-only	LLMs can't parse	Use transcript or written guide

Writing Effective Query Instructions

The queryInstructions field is critical - it tells LLMs exactly what to extract from each URL.

✅ Good Query Instructions:

queryInstructions: |
  Essential reading for OpenShift deployments:
  1. Browse available validated patterns (Multicluster GitOps, Industrial Edge)
  2. Understand the Validated Patterns framework structure
  3. Review pattern architecture and deployment phases
  4. Check prerequisites and infrastructure requirements
  5. Identify which pattern best fits your use case

  This is the PRIMARY source for OpenShift best practices and proven patterns.

Why it's good:

• Numbered steps (clear sequence)
• Specific sections to read
• Explains importance ("PRIMARY source")
• Actionable outcomes ("identify which pattern")

❌ Bad Query Instructions:

queryInstructions: 'Read this documentation'

Why it's bad:

• No specific guidance
• No context on importance
• LLM doesn't know what to extract

Real-World Examples

OpenShift Validated Patterns ✅

authoritativeSources:
  - type: 'documentation'
    url: 'https://validatedpatterns.io/'
    priority: 10
    queryInstructions: |
      Browse available patterns, understand framework, check prerequisites

  - type: 'documentation'
    url: 'https://play.validatedpatterns.io/vp-workshop/main/index.html'
    priority: 10
    queryInstructions: |
      Work through workshop for step-by-step deployment procedures

  - type: 'repository'
    url: 'https://github.com/validatedpatterns/common'
    priority: 10
    queryInstructions: |
      Review framework components, common patterns, Ansible automation

Why this works:

• All three Tier 1 types covered (docs, workshop, code)
• Each serves distinct purpose
• Clear, actionable instructions
• Official Red Hat sources

Firebase Functions ✅

authoritativeSources:
  - type: 'documentation'
    url: 'https://firebase.google.com/docs/functions'
    priority: 10

  - type: 'repository'
    url: 'https://github.com/firebase/functions-samples'
    priority: 10

  - type: 'community'
    url: 'https://firebase.google.com/community'
    priority: 7

Coverage: Official docs + code samples + community

Testing Your URLs

Before finalizing a pattern:

1. Manual Test: Visit each URL and verify:

   • Page loads without authentication
   • Content is technical (not marketing)
   • Information is current (check dates)
   • Steps are actionable

2. LLM Test: Ask an LLM to:

   "Read <URL> and summarize the deployment steps for <pattern>"

   • Can it extract useful information?
   • Does it get accurate details?

3. Validation Script (coming soon):

   npm run validate:pattern-urls

   • Checks URL accessibility
   • Validates response codes
   • Reports broken links

URL Maintenance

Patterns should be living documents:

• Quarterly review: Check all URLs still work
• Version updates: Update URLs when new versions release
• Deprecation handling: Replace deprecated links
• GitHub Actions: Automated URL health checks (weekly)

---

YAML Schema Design

Pattern Definition File Structure

Location: patterns/{platform}-{runtime}.yaml

# patterns/firebase-nodejs.yaml
version: '1.0'
id: 'firebase-nodejs-v1'
name: 'Firebase Cloud Functions (Node.js)'
description: 'Serverless Node.js deployment using Firebase Cloud Functions'

# Pattern composition
composition:
  infrastructure: 'firebase'
  runtime: 'nodejs'
  protocol: 'rest-api'
  strategy: 'serverless'

# Authoritative sources - LLMs query these URLs
authoritativeSources:
  - type: 'documentation'
    url: 'https://firebase.google.com/docs/functions'
    purpose: 'Official Firebase Cloud Functions documentation'
    priority: 10
    requiredForDeployment: true
    queryInstructions: |
      Essential reading:
      1. Get started guide
      2. Triggers (HTTP, database, auth, storage)
      3. Deployment best practices
      4. Security rules
      Start here for all Firebase Functions projects.

  - type: 'repository'
    url: 'https://github.com/firebase/functions-samples'
    purpose: 'Official Firebase Functions code samples'
    priority: 10
    requiredForDeployment: true
    queryInstructions: |
      Browse samples for:
      1. Common triggers (HTTP, Firestore, Auth)
      2. Integration patterns
      3. Testing examples
      4. TypeScript usage
      Use as templates.

  - type: 'documentation'
    url: 'https://firebase.google.com/docs/functions/manage-functions'
    purpose: 'Function lifecycle management guide'
    priority: 9
    requiredForDeployment: false
    queryInstructions: |
      Review for:
      1. Deployment strategies
      2. Environment configuration
      3. Monitoring and logging
      4. Scaling configuration

  - type: 'community'
    url: 'https://github.com/firebase/firebase-js-sdk'
    purpose: 'Firebase JavaScript SDK source code'
    priority: 7
    requiredForDeployment: false
    queryInstructions: |
      Check for:
      1. Latest SDK features
      2. Breaking changes
      3. Migration guides
      4. Best practices in issues/discussions

# Base code repository for starter code
baseCodeRepository:
  url: 'https://github.com/firebase/functions-samples'
  purpose: 'Official Firebase Cloud Functions samples'
  integrationInstructions: |
    1. Browse samples for relevant use case
    2. Copy function structure into functions/src/
    3. Customize business logic
    4. Configure firebase.json
    5. Deploy with firebase deploy
  requiredFiles:
    - 'firebase.json'
    - '.firebaserc'
    - 'functions/package.json'
    - 'functions/src/index.ts'
  scriptEntrypoint: 'firebase deploy --only functions'

# Bill of Materials
dependencies:
  - name: 'firebase-tools'
    type: 'buildtime'
    required: true
    installCommand: 'npm install -g firebase-tools'
    verificationCommand: 'firebase --version'

  - name: 'firebase-admin'
    type: 'runtime'
    required: true
    installCommand: 'npm install firebase-admin'
    verificationCommand: 'npm list firebase-admin'

  - name: 'firebase-functions'
    type: 'runtime'
    required: true
    installCommand: 'npm install firebase-functions'
    verificationCommand: 'npm list firebase-functions'

# Configuration files needed
configurations:
  - path: 'firebase.json'
    purpose: 'Firebase project configuration'
    required: true
    canAutoGenerate: true
    template: |
      {
        "functions": {
          "source": "functions",
          "runtime": "nodejs18",
          "ignore": [
            "node_modules",
            ".git"
          ]
        }
      }

  - path: '.firebaserc'
    purpose: 'Firebase project aliases'
    required: true
    canAutoGenerate: true
    template: |
      {
        "projects": {
          "default": "{{ project-id }}"
        }
      }

  - path: 'functions/package.json'
    purpose: 'Cloud Functions dependencies'
    required: true
    canAutoGenerate: true

  - path: 'functions/.env'
    purpose: 'Environment variables for functions'
    required: false
    canAutoGenerate: true

# Secrets and credentials
secrets:
  - name: 'service-account'
    purpose: 'Firebase Admin SDK service account credentials'
    environmentVariable: 'GOOGLE_APPLICATION_CREDENTIALS'
    required: true

  - name: 'api-keys'
    purpose: 'Third-party API keys used by functions'
    environmentVariable: 'API_KEY'
    required: false

# Infrastructure requirements
infrastructure:
  - component: 'Firebase Project'
    purpose: 'Firebase project with Cloud Functions enabled'
    required: true
    setupCommands:
      - 'firebase login'
      - 'firebase init functions'
    healthCheckCommand: 'firebase projects:list'

  - component: 'Node.js Runtime'
    purpose: 'Node.js runtime for Cloud Functions'
    minimumVersion: '18'
    required: true
    alternatives:
      - 'Node 20'
      - 'Node 22'

# Deployment phases
deploymentPhases:
  - order: 1
    name: 'Firebase Authentication'
    description: 'Authenticate with Firebase'
    estimatedDuration: '1 minute'
    canParallelize: false
    prerequisites: []
    commands:
      - description: 'Login to Firebase'
        command: 'firebase login --no-localhost'
        expectedExitCode: 0

  - order: 2
    name: 'Initialize Firebase Project'
    description: 'Set up Firebase project structure'
    estimatedDuration: '2 minutes'
    canParallelize: false
    prerequisites:
      - 'Firebase Authentication'
    commands:
      - description: 'Initialize Firebase Functions'
        command: 'firebase init functions --project {{ project-id }}'
        expectedExitCode: 0

  - order: 3
    name: 'Install Dependencies'
    description: 'Install Node.js dependencies'
    estimatedDuration: '2-3 minutes'
    canParallelize: false
    prerequisites:
      - 'Initialize Firebase Project'
    commands:
      - description: 'Install function dependencies'
        command: 'cd functions && npm ci'
        expectedExitCode: 0

  - order: 4
    name: 'Deploy Functions'
    description: 'Deploy Cloud Functions to Firebase'
    estimatedDuration: '3-5 minutes'
    canParallelize: false
    prerequisites:
      - 'Install Dependencies'
    commands:
      - description: 'Deploy all functions'
        command: 'firebase deploy --only functions'
        expectedExitCode: 0

# Validation checks
validationChecks:
  - id: 'functions-deployed'
    name: 'Functions Deployment Check'
    description: 'Verify all functions are deployed'
    command: 'firebase functions:list --project {{ project-id }}'
    expectedExitCode: 0
    severity: 'critical'
    failureMessage: 'Functions are not deployed'
    remediationSteps:
      - 'Check deployment logs: firebase functions:log'
      - 'Verify project ID: firebase projects:list'
      - 'Re-deploy: firebase deploy --only functions'

  - id: 'function-health'
    name: 'Function Health Check'
    description: 'Verify function responds to HTTP requests'
    command: 'curl -f {{ function-url }}/health || exit 1'
    expectedExitCode: 0
    severity: 'critical'
    failureMessage: 'Function health endpoint not responding'
    remediationSteps:
      - 'Check function logs: firebase functions:log --only {{ function-name }}'
      - 'Verify function URL in Firebase Console'
      - 'Test locally: firebase emulators:start --only functions'

# Health checks for monitoring
healthChecks:
  - name: 'Function HTTP Health'
    endpoint: '{{ function-url }}/health'
    interval: 60000
    timeout: 10000
    healthyThreshold: 1
    unhealthyThreshold: 3

# Environment-specific overrides
environmentOverrides:
  - environment: 'development'
    overrides:
      deploymentPhases:
        - order: 4
          name: 'Start Emulators'
          description: 'Start Firebase emulators for local testing'
          commands:
            - description: 'Start local emulators'
              command: 'firebase emulators:start --only functions'
              expectedExitCode: 0

# Pattern metadata
metadata:
  source: 'Firebase Documentation'
  lastUpdated: '2025-01-19'
  maintainer: 'Google Firebase'
  tags:
    - 'firebase'
    - 'serverless'
    - 'cloud-functions'
    - 'nodejs'
    - 'google-cloud'
  contributors:
    - name: 'Your Name'
      github: 'yourusername'
  changeLog:
    - version: '1.0'
      date: '2025-01-19'
      changes:
        - 'Initial Firebase Node.js pattern'
        - 'Added emulator support for development'

# Platform detection hints (for auto-detection)
detectionHints:
  requiredFiles:
    - 'firebase.json'
  optionalFiles:
    - 'functions/'
    - '.firebaserc'
  confidence:
    firebase.json: 0.9
    functions/: 0.8
    .firebaserc: 0.7

---

Directory Structure

patterns/
├── README.md                      # Pattern contribution guide
├── schema.json                    # JSON Schema for validation
├── infrastructure/                # Infrastructure-only patterns
│   ├── openshift.yaml
│   ├── kubernetes.yaml
│   ├── docker.yaml
│   ├── aws.yaml
│   └── azure.yaml
├── runtime/                       # Runtime-only patterns
│   ├── nodejs.yaml
│   ├── python.yaml
│   ├── java.yaml
│   └── go.yaml
├── composite/                     # Composite patterns (infra + runtime)
│   ├── firebase-nodejs.yaml       # NEW
│   ├── firebase-python.yaml       # NEW
│   ├── aws-lambda-nodejs.yaml     # NEW
│   ├── aws-lambda-python.yaml
│   ├── azure-functions-nodejs.yaml
│   ├── gcp-cloudrun-go.yaml
│   ├── openshift-nodejs-gitops.yaml
│   └── kubernetes-python-django.yaml
└── protocol/                      # Protocol patterns
    ├── mcp.yaml
    └── a2a.yaml

---

JSON Schema for Validation

File: patterns/schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Validated Pattern Definition",
  "type": "object",
  "required": ["version", "id", "name", "description", "authoritativeSources", "deploymentPhases"],
  "properties": {
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$"
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9-]+$"
    },
    "name": {
      "type": "string",
      "minLength": 5
    },
    "description": {
      "type": "string",
      "minLength": 20
    },
    "composition": {
      "type": "object",
      "properties": {
        "infrastructure": {
          "type": "string",
          "enum": ["openshift", "kubernetes", "docker", "firebase", "aws", "azure", "gcp"]
        },
        "runtime": {
          "type": "string",
          "enum": ["nodejs", "python", "java", "go", "rust", "dotnet"]
        },
        "protocol": {
          "type": "string",
          "enum": ["mcp", "a2a", "rest-api", "grpc", "graphql"]
        },
        "strategy": {
          "type": "string",
          "enum": ["gitops", "blue-green", "canary", "rolling", "serverless", "container"]
        }
      }
    },
    "authoritativeSources": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "type",
          "url",
          "purpose",
          "priority",
          "requiredForDeployment",
          "queryInstructions"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["documentation", "repository", "specification", "examples", "community"]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "purpose": {
            "type": "string",
            "minLength": 10
          },
          "priority": {
            "type": "number",
            "minimum": 1,
            "maximum": 10
          },
          "requiredForDeployment": {
            "type": "boolean"
          },
          "queryInstructions": {
            "type": "string",
            "minLength": 20
          }
        }
      }
    }
  }
}

---

GitHub Actions Workflow

1. Pattern Validation on PR

File: .github/workflows/validate-patterns.yml

name: Validate Pattern Definitions

on:
  pull_request:
    paths:
      - 'patterns/**/*.yaml'
      - 'patterns/**/*.json'
  push:
    branches:
      - main
    paths:
      - 'patterns/**/*.yaml'

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Validate YAML syntax
        run: |
          npm install -g yaml-validator
          yaml-validator patterns/**/*.yaml

      - name: Validate against JSON Schema
        run: |
          npm install -g ajv-cli
          for file in patterns/**/*.yaml; do
            echo "Validating $file"
            ajv validate -s patterns/schema.json -d "$file" --spec=draft7
          done

      - name: Check authoritative source URLs
        run: node scripts/validate-pattern-urls.js

      - name: Lint pattern definitions
        run: npm run lint:patterns

2. URL Health Check (Weekly)

File: .github/workflows/check-pattern-urls.yml

name: Check Pattern URLs

on:
  schedule:
    - cron: '0 0 * * 0' # Weekly on Sunday
  workflow_dispatch:

jobs:
  check-urls:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Check all pattern URLs
        id: url-check
        run: |
          node scripts/check-pattern-urls.js > url-report.txt
          cat url-report.txt
        continue-on-error: true

      - name: Create issue if URLs are broken
        if: steps.url-check.outcome == 'failure'
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('url-report.txt', 'utf8');

            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: '🔗 Broken URLs in Pattern Definitions',
              body: `## URL Health Check Failed\n\n\`\`\`\n${report}\n\`\`\`\n\nPlease update the pattern files with working URLs.`,
              labels: ['patterns', 'url-check', 'automated']
            });

3. Build and Release on Pattern Update

File: .github/workflows/build-patterns.yml

name: Build and Release Patterns

on:
  push:
    branches:
      - main
    paths:
      - 'patterns/**/*.yaml'

jobs:
  build-and-release:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Build pattern definitions
        run: npm run build:patterns

      - name: Run tests
        run: npm test

      - name: Determine version bump
        id: version
        run: |
          # Get changed files
          CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD | grep '^patterns/')

          # Determine bump type based on changes
          if echo "$CHANGED_FILES" | grep -q 'patterns/composite/'; then
            echo "bump=minor" >> $GITHUB_OUTPUT
          else
            echo "bump=patch" >> $GITHUB_OUTPUT
          fi

      - name: Bump version
        run: |
          npm version ${{ steps.version.outputs.bump }} --no-git-tag-version
          NEW_VERSION=$(node -p "require('./package.json').version")
          echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV

      - name: Commit version bump
        run: |
          git config user.name "github-actions"
          git config user.email "github-actions@github.com"
          git add package.json
          git commit -m "chore: bump version to ${{ env.NEW_VERSION }} [skip ci]"
          git push

      - name: Create release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: v${{ env.NEW_VERSION }}
          release_name: Patterns Release v${{ env.NEW_VERSION }}
          body: |
            ## Pattern Updates

            Updated validated pattern definitions.

            ### Changed Files
            ${{ steps.files.outputs.changed }}
          draft: false
          prerelease: false

---

URL Validation Script

File: scripts/validate-pattern-urls.js

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const yaml = require('js-yaml');
const fetch = require('node-fetch');

async function checkUrl(url, timeout = 10000) {
  try {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), timeout);

    const response = await fetch(url, {
      method: 'HEAD',
      signal: controller.signal,
      headers: {
        'User-Agent': 'MCP-ADR-Pattern-Validator/1.0',
      },
    });

    clearTimeout(timeoutId);
    return {
      url,
      status: response.status,
      ok: response.ok,
    };
  } catch (error) {
    return {
      url,
      status: 0,
      ok: false,
      error: error.message,
    };
  }
}

async function validatePatternFile(filePath) {
  console.log(`\nValidating: ${filePath}`);

  const content = fs.readFileSync(filePath, 'utf8');
  const pattern = yaml.load(content);

  const results = [];

  // Check authoritative sources
  if (pattern.authoritativeSources) {
    for (const source of pattern.authoritativeSources) {
      console.log(`  Checking: ${source.url}`);
      const result = await checkUrl(source.url);
      results.push({
        file: filePath,
        source: source.purpose,
        ...result,
      });
    }
  }

  // Check base code repository
  if (pattern.baseCodeRepository?.url) {
    console.log(`  Checking: ${pattern.baseCodeRepository.url}`);
    const result = await checkUrl(pattern.baseCodeRepository.url);
    results.push({
      file: filePath,
      source: 'Base Repository',
      ...result,
    });
  }

  return results;
}

async function main() {
  const patternsDir = path.join(__dirname, '..', 'patterns');
  const patternFiles = [];

  // Find all YAML files
  function findYamlFiles(dir) {
    const files = fs.readdirSync(dir);
    for (const file of files) {
      const filePath = path.join(dir, file);
      const stat = fs.statSync(filePath);

      if (stat.isDirectory()) {
        findYamlFiles(filePath);
      } else if (file.endsWith('.yaml') || file.endsWith('.yml')) {
        patternFiles.push(filePath);
      }
    }
  }

  findYamlFiles(patternsDir);

  console.log(`Found ${patternFiles.length} pattern files to validate`);

  let allResults = [];
  for (const file of patternFiles) {
    const results = await validatePatternFile(file);
    allResults = allResults.concat(results);
  }

  // Report results
  const broken = allResults.filter(r => !r.ok);

  if (broken.length > 0) {
    console.error('\n❌ BROKEN URLS FOUND:');
    for (const result of broken) {
      console.error(`  ${result.file}`);
      console.error(`    ${result.source}: ${result.url}`);
      console.error(`    Status: ${result.status} ${result.error || ''}`);
    }
    process.exit(1);
  } else {
    console.log('\n✅ All URLs are valid!');
    process.exit(0);
  }
}

main().catch(error => {
  console.error('Error:', error);
  process.exit(1);
});

---

Pattern Loader Utility

File: src/utils/pattern-loader.ts

import { promises as fs } from 'fs';
import * as path from 'path';
import * as yaml from 'js-yaml';
import { EnhancedLogger } from './enhanced-logging.js';

export interface DynamicPattern {
  version: string;
  id: string;
  name: string;
  description: string;
  composition?: {
    infrastructure?: string;
    runtime?: string;
    protocol?: string;
    strategy?: string;
  };
  authoritativeSources: Array<{
    type: string;
    url: string;
    purpose: string;
    priority: number;
    requiredForDeployment: boolean;
    queryInstructions: string;
  }>;
  // ... other fields from YAML
}

export class PatternLoader {
  private logger: EnhancedLogger;
  private patternsDir: string;
  private cache: Map<string, DynamicPattern> = new Map();

  constructor(patternsDir?: string) {
    this.logger = new EnhancedLogger();
    this.patternsDir = patternsDir || path.join(__dirname, '../../patterns');
  }

  /**
   * Load pattern from YAML file
   */
  async loadPattern(patternId: string): Promise<DynamicPattern | null> {
    // Check cache first
    if (this.cache.has(patternId)) {
      return this.cache.get(patternId)!;
    }

    try {
      // Try different directories
      const directories = ['composite', 'infrastructure', 'runtime', 'protocol'];

      for (const dir of directories) {
        const filePath = path.join(this.patternsDir, dir, `${patternId}.yaml`);

        try {
          const content = await fs.readFile(filePath, 'utf-8');
          const pattern = yaml.load(content) as DynamicPattern;

          // Validate pattern
          this.validatePattern(pattern);

          // Cache it
          this.cache.set(patternId, pattern);

          this.logger.info(`Loaded pattern: ${patternId}`, 'PatternLoader');
          return pattern;
        } catch (error: any) {
          if (error.code !== 'ENOENT') {
            throw error; // Re-throw non-file-not-found errors
          }
          // Continue to next directory
        }
      }

      this.logger.warn(`Pattern not found: ${patternId}`, 'PatternLoader');
      return null;
    } catch (error) {
      this.logger.error(`Failed to load pattern: ${patternId}`, 'PatternLoader', error as Error);
      return null;
    }
  }

  /**
   * Load pattern by composition
   */
  async loadPatternByComposition(
    infrastructure: string,
    runtime?: string
  ): Promise<DynamicPattern | null> {
    const compositeId = runtime ? `${infrastructure}-${runtime}` : infrastructure;

    // Try composite first
    let pattern = await this.loadPattern(compositeId);

    // Fallback to infrastructure-only
    if (!pattern && runtime) {
      pattern = await this.loadPattern(infrastructure);
    }

    return pattern;
  }

  /**
   * List all available patterns
   */
  async listPatterns(): Promise<string[]> {
    const patterns: string[] = [];
    const directories = ['composite', 'infrastructure', 'runtime', 'protocol'];

    for (const dir of directories) {
      const dirPath = path.join(this.patternsDir, dir);

      try {
        const files = await fs.readdir(dirPath);
        const yamlFiles = files.filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));

        for (const file of yamlFiles) {
          const patternId = file.replace(/\.(yaml|yml)$/, '');
          patterns.push(patternId);
        }
      } catch (error: any) {
        if (error.code !== 'ENOENT') {
          throw error;
        }
      }
    }

    return patterns;
  }

  /**
   * Validate pattern structure
   */
  private validatePattern(pattern: DynamicPattern): void {
    if (!pattern.id || !pattern.name || !pattern.version) {
      throw new Error('Pattern missing required fields: id, name, version');
    }

    if (!pattern.authoritativeSources || pattern.authoritativeSources.length === 0) {
      throw new Error('Pattern must have at least one authoritative source');
    }

    // Validate URLs
    for (const source of pattern.authoritativeSources) {
      try {
        new URL(source.url);
      } catch {
        throw new Error(`Invalid URL in pattern ${pattern.id}: ${source.url}`);
      }
    }
  }

  /**
   * Clear cache (useful for testing or reloading)
   */
  clearCache(): void {
    this.cache.clear();
  }
}

---

Bootstrap Tool Integration

Update: src/tools/bootstrap-validation-loop-tool.ts

import { PatternLoader, DynamicPattern } from '../utils/pattern-loader.js';

export class BootstrapValidationLoop {
  private patternLoader: PatternLoader;

  constructor(projectPath: string, adrDirectory: string) {
    // ... existing initialization
    this.patternLoader = new PatternLoader();
  }

  async executeLoop(args: any): Promise<any> {
    // STEP 0: Detect platform
    this.platformDetection = await detectPlatforms(this.projectPath);
    const runtimeDetection = await detectRuntime(this.projectPath);

    // STEP 0.1: Load pattern from YAML (instead of hardcoded TypeScript)
    this.logger.info('Loading validated pattern from YAML...', 'BootstrapValidationLoop');

    const dynamicPattern = await this.patternLoader.loadPatternByComposition(
      this.platformDetection.primaryPlatform,
      runtimeDetection.runtime
    );

    if (dynamicPattern) {
      this.logger.info(
        `✅ Loaded pattern: ${dynamicPattern.name} v${dynamicPattern.version}`,
        'BootstrapValidationLoop',
        {
          composition: dynamicPattern.composition,
          authoritativeSources: dynamicPattern.authoritativeSources.length,
        }
      );

      // STEP 0.2: LLM should query authoritative sources
      const requiredSources = dynamicPattern.authoritativeSources.filter(
        s => s.requiredForDeployment
      );

      this.logger.info(
        `⚠️  IMPORTANT: Query ${requiredSources.length} REQUIRED authoritative sources:`,
        'BootstrapValidationLoop'
      );

      for (const source of requiredSources) {
        this.logger.info(`  📚 ${source.type}: ${source.url}`, 'BootstrapValidationLoop');
        this.logger.info(`     Purpose: ${source.purpose}`, 'BootstrapValidationLoop');
        this.logger.info(
          `     Query instructions: ${source.queryInstructions}`,
          'BootstrapValidationLoop'
        );
      }
    } else {
      this.logger.warn(
        `No pattern found for ${this.platformDetection.primaryPlatform}${runtimeDetection.runtime ? ` + ${runtimeDetection.runtime}` : ''}`,
        'BootstrapValidationLoop'
      );
    }

    // Continue with deployment...
  }
}

---

Benefits

1. Easy Updates

# User updates Firebase pattern
vim patterns/composite/firebase-nodejs.yaml
# Change URL from old doc to new doc
git commit -m "fix: update Firebase Functions docs URL"
git push

# GitHub Action:
# ✅ Validates new URL is reachable
# ✅ Rebuilds pattern definitions
# ✅ Creates new release
# ✅ LLMs use updated pattern immediately

2. Multiple Sources for Rich Context

authoritativeSources:
  - type: 'documentation'
    url: 'https://firebase.google.com/docs/functions'
    priority: 10

  - type: 'repository'
    url: 'https://github.com/firebase/functions-samples'
    priority: 10

  - type: 'community'
    url: 'https://stackoverflow.com/questions/tagged/firebase-cloud-functions'
    priority: 7

  - type: 'examples'
    url: 'https://github.com/firebase/quickstart-nodejs'
    priority: 8

LLM queries all sources for comprehensive context!

3. Community Contributions

Non-developers can add patterns:

# Fork repo
# Add patterns/composite/vercel-nextjs.yaml
# Submit PR
# CI validates URLs
# Merged and released!

4. Link Validation

Weekly GitHub Action checks all URLs:

• ✅ Creates issue if links are broken
• ✅ Notifies maintainers
• ✅ Prevents deployment with bad links

---

Migration Path

Week 1: Infrastructure

1. Create patterns/ directory structure
2. Create JSON schema
3. Create GitHub Actions workflows
4. Create PatternLoader utility

Week 2: Convert Existing Patterns

1. Convert OpenShift pattern to YAML
2. Convert Kubernetes pattern to YAML
3. Convert Docker pattern to YAML
4. Test pattern loading

Week 3: Add New Patterns

1. Create Firebase Node.js pattern (YAML)
2. Create AWS Lambda patterns
3. Create Azure Functions patterns
4. Test with bootstrap tool

Week 4: Integrate & Test

1. Update bootstrap tool to use PatternLoader
2. Update context generation
3. Test end-to-end
4. Document pattern contribution process

---

Example: Adding New Pattern

Contributor workflow:

1. Create patterns/composite/vercel-nextjs.yaml:

version: '1.0'
id: 'vercel-nextjs-v1'
name: 'Vercel Next.js Deployment'
description: 'Serverless Next.js deployment on Vercel'

authoritativeSources:
  - type: 'documentation'
    url: 'https://vercel.com/docs'
    purpose: 'Official Vercel documentation'
    priority: 10
    requiredForDeployment: true
    queryInstructions: |
      Read getting started guide and deployment options

2. Commit and push
3. GitHub Action validates:
   • ✅ YAML syntax
   • ✅ Schema compliance
   • ✅ URL reachability
4. Create PR
5. Merged → New release created automatically
6. LLMs can now use Vercel pattern!

---

This approach is much better than hardcoding! What do you think?

Should I start implementing this system?