openshift · Prashanth684 · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
diff --git a/.github/workflows/validate-agentic-docs.yml b/.github/workflows/validate-agentic-docs.yml
@@ -0,0 +1,154 @@
+name: Validate Agentic Documentation
+
+on:
+  pull_request:
+    paths:
+      - 'agentic/**'
+      - '*.md'
+      - '.github/workflows/validate-agentic-docs.yml'
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  structure:
+    name: Validate Structure
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check AGENTS.md length
+        run: |
+          lines=$(wc -l < AGENTS.md)
+          echo "AGENTS.md has $lines lines"
+          if [ $lines -gt 150 ]; then
+            echo "❌ AGENTS.md too long ($lines lines). Keep under 150."
+            exit 1
+          fi
+          echo "✅ AGENTS.md length OK"
+
+      - name: Verify directory structure
+        run: |
+          required_dirs="design-docs domain exec-plans product-specs decisions references generated"
+          for dir in $required_dirs; do
+            if [ ! -d "agentic/$dir" ]; then
+              echo "❌ Missing required directory: agentic/$dir"
+              exit 1
+            fi
+          done
+          echo "✅ Directory structure OK"
+
+      - name: Check index files exist
+        run: |
+          required_indexes="design-docs/index.md domain/index.md product-specs/index.md decisions/index.md references/index.md"
+          for index in $required_indexes; do
+            if [ ! -f "agentic/$index" ]; then
+              echo "❌ Missing required index: agentic/$index"
+              exit 1
+            fi
+          done
+          echo "✅ Index files OK"
+
+      - name: Check required top-level files exist
+        run: |
+          required_files="DESIGN.md DEVELOPMENT.md TESTING.md RELIABILITY.md SECURITY.md QUALITY_SCORE.md"
+          for file in $required_files; do
+            if [ ! -f "agentic/$file" ]; then
+              echo "❌ Missing REQUIRED file: agentic/$file"
+              echo "   These 6 files are mandatory for ALL repositories."
+              exit 1
+            fi
+          done
+          echo "✅ All required top-level files present"
+
+      - name: Check for unreplaced placeholders
+        run: |
+          # Check for common placeholder patterns (excluding valid markdown links)
+          if grep -r '\[REPO-NAME\]\|\[Component1\]\|\[Concept1\]' agentic/ AGENTS.md ARCHITECTURE.md 2>/dev/null | grep -v ']('; then
+            echo "❌ Found unreplaced placeholders"
+            exit 1
+          fi
+          echo "✅ No unreplaced placeholders found"
+
+  links:
+    name: Validate Links
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check markdown links
+        uses: lycheeverse/lychee-action@v1
+        with:
+          args: --verbose --no-progress 'agentic/**/*.md' 'AGENTS.md' 'ARCHITECTURE.md'
+          fail: true
+
+  frontmatter:
+    name: Validate Frontmatter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check exec-plan frontmatter
+        run: |
+          for file in agentic/exec-plans/active/*.md agentic/exec-plans/completed/*.md; do
+            if [ -f "$file" ] && [ "$(basename "$file")" != "template.md" ]; then
+              if ! head -n 1 "$file" | grep -q "^---$"; then
+                echo "❌ $file missing YAML frontmatter"
+                exit 1
+              fi
+            fi
+          done
+          echo "✅ Exec-plan frontmatter OK"
+
+      - name: Check ADR frontmatter
+        run: |
+          for file in agentic/decisions/adr-*.md; do
+            if [ -f "$file" ] && [ "$(basename "$file")" != "adr-template.md" ]; then
+              if ! head -n 1 "$file" | grep -q "^---$"; then
+                echo "❌ $file missing YAML frontmatter"
+                exit 1
+              fi
+            fi
+          done
+          echo "✅ ADR frontmatter OK"
+
+      - name: Check concept frontmatter
+        run: |
+          for file in agentic/domain/concepts/*.md; do
+            if [ -f "$file" ]; then
+              if ! head -n 1 "$file" | grep -q "^---$"; then
+                echo "❌ $file missing YAML frontmatter"
+                exit 1
+              fi
+            fi
+          done
+          echo "✅ Concept frontmatter OK"
+
+  freshness:
+    name: Check Freshness
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for stale TODOs
+        run: |
+          stale_count=0
+          while IFS= read -r file; do
+            last_modified=$(git log -1 --format=%ct "$file" 2>/dev/null || echo 0)
+            now=$(date +%s)
+            days=$(( ($now - $last_modified) / 86400 ))
+
+            if [ $days -gt 30 ] && grep -q "TODO" "$file"; then
+              echo "⚠️  $file has TODO and hasn't been updated in $days days"
+              stale_count=$((stale_count + 1))
+            fi
+          done < <(find agentic -name "*.md" -type f)
+
+          if [ $stale_count -gt 5 ]; then
+            echo "❌ Too many stale TODOs ($stale_count). Update or move to tech-debt-tracker.md"
+            exit 1
+          fi
+          echo "✅ TODO freshness OK"
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,149 @@
+# multiarch-tuning-operator - Agent Navigation
+
+> **Purpose**: Table of contents for AI agents. Points to deeper knowledge.
+> **Do not expand this file**. Keep under 150 lines. Link to details instead.
+>
+> **New here?** Start with [README.md](./README.md) for project overview.
+
+## What This Repository Does
+
+Enhances operational experience within multi-architecture OpenShift clusters by providing architecture-aware scheduling of workloads through automatic nodeAffinity configuration based on container image architectures.
+
+## Quick Navigation by Intent
+
+**I need to understand the system**
+→ [ARCHITECTURE.md](./ARCHITECTURE.md)
+→ [Core beliefs](./agentic/design-docs/core-beliefs.md)
+→ [Design docs index](./agentic/design-docs/index.md)
+→ [Architecture decisions](./agentic/decisions/index.md)
+
+**I'm implementing a feature**
+1. INVESTIGATE: Read [ARCHITECTURE.md](./ARCHITECTURE.md), [design guide](./agentic/DESIGN.md), verify data structures
+2. CREATE plan in [active plans](./agentic/exec-plans/active/index.md) using [template](./agentic/exec-plans/template.md)
+3. READ [testing guide](./agentic/TESTING.md) and patterns
+4. Implement with tests
+5. Update plan to completed
+
+**I'm reviewing security**
+→ [Security model](./agentic/SECURITY.md)
+→ [Core beliefs](./agentic/design-docs/core-beliefs.md)
+
+**I need reliability context**
+→ [Reliability guide](./agentic/RELIABILITY.md)
+→ [Testing strategy](./agentic/TESTING.md)
+
+**I'm fixing a bug**
+→ [Component map](./ARCHITECTURE.md#components)
+→ [Debugging](./agentic/DEVELOPMENT.md#debugging)
+→ [Tests](./agentic/TESTING.md)
+
+**I need to understand a concept**
+→ [Domain documentation index](./agentic/domain/index.md)
+→ [Glossary](./agentic/domain/glossary.md)
+→ [Concepts](./agentic/domain/concepts/)
+
+## Repository Structure
+
+```
+pkg/controllers/{operator,podplacement}  # Core controllers
+pkg/image/                                # Image inspection
+test/e2e/                                 # E2E tests
+```
+
+## Component Boundaries
+
+```
+┌────────────────────────────────┐
+│  Operator Controller           │  Manages ClusterPodPlacementConfig CR
+└────────────────────────────────┘
+         ↓ deploys
+┌────────────────────────────────┐
+│  Pod Placement Webhook         │  Adds scheduling gates to pods
+└────────────────────────────────┘
+         ↓ gates pod
+┌────────────────────────────────┐
+│  Pod Placement Controller      │  Inspects images, sets nodeAffinity
+└────────────────────────────────┘
+         ↓ ungates pod
+┌────────────────────────────────┐
+│  Kubernetes Scheduler          │  Places pod on appropriate node
+└────────────────────────────────┘
+```
+
+## Core Concepts (Domain Model)
+
+| Concept | Definition | Docs |
+|---------|-----------|------|
+| ClusterPodPlacementConfig | Singleton CR controlling pod placement operand | [./agentic/domain/concepts/cluster-pod-placement-config.md](./agentic/domain/concepts/cluster-pod-placement-config.md) |
+| Scheduling Gate | Kubernetes mechanism to hold pods before scheduling | [./agentic/domain/concepts/scheduling-gate.md](./agentic/domain/concepts/scheduling-gate.md) |
+| Image Inspection | Determining supported architectures from container images | [./agentic/domain/concepts/image-inspection.md](./agentic/domain/concepts/image-inspection.md) |
+| NodeAffinity | Kubernetes constraint for node selection | [./agentic/domain/concepts/node-affinity.md](./agentic/domain/concepts/node-affinity.md) |
+| Pod Placement Operand | Controllers and webhook that perform scheduling | [./agentic/domain/concepts/pod-placement-operand.md](./agentic/domain/concepts/pod-placement-operand.md) |
+
+## Key Invariants (ENFORCE THESE)
+
+1. **ClusterPodPlacementConfig is Singleton**: Only resource named "cluster" allowed
+   - Validated by: Validating webhook
+   - Why: Single point of configuration for cluster-wide behavior
+
+2. **System Namespaces Excluded**: openshift-*, kube-*, hypershift-* always excluded
+   - Validated by: Webhook namespace selector
+   - Why: Prevent interference with platform components
+
+3. **All features require execution plans**: Must create plan in agentic/exec-plans/active/ before coding
+   - Validated by: Code review
+   - Why: Ensures design consideration and trackable decision history
+
+## Critical Code Locations
+
+| Purpose | File | Why Critical |
+|---------|------|--------------|
+| Pod reconciliation logic | controllers/podplacement/pod_reconciler.go | Core pod processing workflow |
+| Image architecture detection | pkg/image/inspector.go | Determines supported architectures |
+| Scheduling gate webhook | controllers/podplacement/scheduling_gate_mutating_webhook.go | Adds gates to pods |
+| Operator reconciliation | controllers/operator/clusterpodplacementconfig_controller.go | Manages operand lifecycle |
+
+## External Dependencies
+
+- **controller-runtime**: Operator framework | **containers/image**: Image inspection | **OpenShift API**: CRDs
+
+## Build & Test
+
+```bash
+# Build
+make build
+
+# Unit tests
+make unit
+
+# E2E tests (requires deployed operator)
+KUBECONFIG=/path/to/kubeconfig NAMESPACE=openshift-multiarch-tuning-operator make e2e
+
+# All checks (lint, vet, gosec, goimports, tests)
+make test
+```
+
+## Documentation Structure
+
+- [Design docs](./agentic/design-docs/index.md) - Architecture, components, patterns
+- [Domain](./agentic/domain/index.md) - Concepts, glossary, workflows
+- [Exec plans](./agentic/exec-plans/active/) - Active work tracking
+- [Product specs](./agentic/product-specs/index.md) - Feature specifications
+- [Decisions](./agentic/decisions/index.md) - Architecture Decision Records (ADRs)
+- [References](./agentic/references/index.md) - External knowledge, primers
+- [DESIGN.md](./agentic/DESIGN.md) - Design philosophy
+- [DEVELOPMENT.md](./agentic/DEVELOPMENT.md) - Development setup
+- [TESTING.md](./agentic/TESTING.md) - Test strategy
+- [RELIABILITY.md](./agentic/RELIABILITY.md) - SLOs, observability
+- [SECURITY.md](./agentic/SECURITY.md) - Security model
+- [QUALITY_SCORE.md](./agentic/QUALITY_SCORE.md) - Documentation quality metrics
+
+## When You're Stuck
+
+1. Check [tech debt tracker](./agentic/exec-plans/tech-debt-tracker.md)
+2. Check [quality score](./agentic/QUALITY_SCORE.md)
+3. File a plan in [active plans](./agentic/exec-plans/active/)
+
+## Last Updated
+
+This file is validated by CI on every commit.