diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 4d64c844c..b9bf51615 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -246,6 +246,12 @@
       "source": "./plugins/marketplace-ops",
       "description": "Maintenance commands for Claude Code plugin marketplaces",
       "version": "0.1.2"
+    },
+    {
+      "name": "agentic-docs",
+      "source": "./plugins/agentic-docs",
+      "description": "Create and maintain AI-optimized documentation for OpenShift",
+      "version": "1.0.0"
     }
   ]
 }
diff --git a/docs/data.json b/docs/data.json
index 912793933..8ff350327 100644
--- a/docs/data.json
+++ b/docs/data.json
@@ -1822,6 +1822,26 @@
       "name": "marketplace-ops",
       "skills": [],
       "version": "0.1.2"
+    },
+    {
+      "commands": [],
+      "description": "Create and maintain AI-optimized documentation for OpenShift",
+      "has_readme": true,
+      "hooks": [],
+      "name": "agentic-docs",
+      "skills": [
+        {
+          "description": "Create lean component documentation for OpenShift repositories",
+          "id": "component-docs",
+          "name": "component-docs"
+        },
+        {
+          "description": "Update existing platform documentation with automatic gap detection in openshift/enhancements",
+          "id": "update-platform-docs",
+          "name": "update-platform-docs"
+        }
+      ],
+      "version": "1.0.0"
     }
   ]
 }
\ No newline at end of file
diff --git a/plugins/agentic-docs/.claude-plugin/plugin.json b/plugins/agentic-docs/.claude-plugin/plugin.json
new file mode 100644
index 000000000..af97be8af
--- /dev/null
+++ b/plugins/agentic-docs/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "agentic-docs",
+  "description": "Create and maintain AI-optimized documentation for OpenShift",
+  "version": "1.0.0",
+  "author": {
+    "name": "github.com/openshift-eng"
+  }
+}
diff --git a/plugins/agentic-docs/OWNERS b/plugins/agentic-docs/OWNERS
new file mode 100644
index 000000000..c6d6e3031
--- /dev/null
+++ b/plugins/agentic-docs/OWNERS
@@ -0,0 +1,10 @@
+approvers:
+- Prashanth684
+- kenjpais
+- jatinsu
+- andymcc
+reviewers:
+- Prashanth684
+- kenjpais
+- jatinsu
+- andymcc
diff --git a/plugins/agentic-docs/README.md b/plugins/agentic-docs/README.md
new file mode 100644
index 000000000..961c070db
--- /dev/null
+++ b/plugins/agentic-docs/README.md
@@ -0,0 +1,39 @@
+# Agentic Docs
+
+AI-optimized OpenShift documentation with progressive disclosure, reference style (tables/checklists), and pointer-based navigation.
+
+## Two-Tier Architecture
+
+**Platform Docs** (`openshift/enhancements/ai-docs/`) - **Already exists**  
+Generic patterns, testing, security, K8s/OpenShift fundamentals, cross-repo ADRs. ~34 files, 4.4k lines.
+
+**Component Docs** (`{component}/ai-docs/`)  
+Component CRDs, architecture, local ADRs, exec-plans. Links to platform docs. ~15 files, 2.5k lines (58% leaner).
+
+## Skills
+
+### `/update-platform-docs`
+Incrementally update platform docs with automatic gap detection.
+
+```bash
+cd /path/to/openshift/enhancements
+/update-platform-docs
+```
+
+Scans ai-docs/, reports missing files, lets you fill gaps or add custom content. Auto-updates indexes/navigation and validates conventions. Use for incremental changes to existing platform documentation.
+
+### `/component-docs`
+Creates lean component docs in component repositories.
+
+```bash
+cd /path/to/component-repository
+/component-docs
+```
+
+Creates AGENTS.md + ai-docs/ with: component CRDs only, architecture, component ADRs, exec-plans, ecosystem links to platform docs, development/testing guides. Excludes generic patterns (lives in platform docs). Example: [machine-config-operator/ai-docs](https://github.com/openshift/machine-config-operator/tree/master/ai-docs).
+
+## Development
+
+Skills live under `skills/{update-platform-docs,component-docs}/` with SKILL.md, scripts, and templates.
+
+**License:** Apache 2.0
diff --git a/plugins/agentic-docs/skills/component-docs/SKILL.md b/plugins/agentic-docs/skills/component-docs/SKILL.md
new file mode 100644
index 000000000..71b73fddb
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/SKILL.md
@@ -0,0 +1,526 @@
+---
+name: component-docs
+description: Create lean component documentation for OpenShift repositories
+trigger: explicit
+model: sonnet
+---
+
+# Component Documentation Creator
+
+Creates lean component agentic documentation for OpenShift component repositories.
+
+**Philosophy**: Component docs contain ONLY component-specific knowledge. Generic platform patterns live in platform (openshift/enhancements/ai-docs/).
+
+## Two-Tier Architecture
+
+### Platform: Platform Hub (openshift/enhancements/ai-docs/)
+**Contains**: Operator patterns, testing practices, security guidelines, Kubernetes/OpenShift fundamentals, cross-repo ADRs
+
+### Component: Component Repos (LEAN)
+**Contains**: Component-specific CRDs, component architecture, component ADRs, exec-plans
+
+**Decision Rule**: "Would another repo need to duplicate this?"
+- YES → Platform (platform)
+- NO → Component (component)
+
+## What Gets Created
+
+```text
+component-repo/
+├── AGENTS.md                      # Master entry point (80-100 lines)
+└── ai-docs/
+    ├── domain/                    # Component CRDs ONLY
+    ├── architecture/              # Component internals
+    │   └── components.md
+    ├── decisions/                 # Component ADRs ONLY
+    │   ├── adr-0001-*.md
+    │   └── adr-template.md
+    ├── exec-plans/
+    │   ├── active/                # Features being implemented
+    │   └── README.md              # Pointer to Platform guidance
+    ├── references/
+    │   └── ecosystem.md           # Links to Platform (CRITICAL)
+    ├── [COMPONENT]_DEVELOPMENT.md
+    └── [COMPONENT]_TESTING.md
+```text
+
+## What NOT to Include (lives in Platform)
+
+❌ Generic operator patterns (controller-runtime, status conditions)  
+❌ Testing practices (test pyramid, E2E framework)  
+❌ Security practices (STRIDE, RBAC guidelines)  
+❌ Reliability practices (SLO framework)  
+❌ Kubernetes fundamentals (Pod, Node, Service)  
+❌ Cross-repo ADRs (etcd, CVO orchestration, immutable nodes)
+
+## Execution Workflow
+
+### Phase 1: Setup
+- [ ] Find skill directory: `SKILL_DIR=$(find ~/.claude/plugins/cache -path "*/component-docs" -type d | head -1)`
+- [ ] Determine repo path: `REPO_PATH="${provided_path:-$PWD}"`
+- [ ] Detect component name from repo (e.g., machine-config-operator → MCO)
+- [ ] Run `bash "$SKILL_DIR/scripts/create-structure.sh" "$REPO_PATH"`
+
+### Phase 2: Create AGENTS.md (80-100 lines)
+- [ ] Create master entry point at repo root
+- [ ] Include compressed index of component docs
+- [ ] Add retrieval-first instruction
+- [ ] Add Platform ecosystem hub links
+- [ ] Add component quick navigation
+- [ ] Validate line count: `wc -l AGENTS.md` (target: 80-100)
+
+### Phase 3: Component Domain Concepts
+- [ ] Identify component-specific CRDs (via `oc api-resources`)
+- [ ] Create domain/*.md for each CRD
+- [ ] Document CRD purpose, key fields, lifecycle
+- [ ] Use `templates/domain-concept-template.md` for structure
+- [ ] Focus on component-specific behavior, link to Platform for generic patterns
+
+### Phase 4: Component Architecture
+- [ ] Create architecture/components.md
+- [ ] Document component structure (pkg/, cmd/, controllers/)
+- [ ] Explain component relationships and data flow
+- [ ] Keep lean (100-200 lines)
+
+### Phase 5: Component ADRs
+- [ ] Create decisions/adr-template.md (copy from templates)
+- [ ] Create 2-3 component-specific ADRs
+- [ ] Example: rpm-ostree choice, Ignition format, config drift detection
+- [ ] NO cross-repo ADRs (those go in Platform)
+
+### Phase 6: Exec-Plans
+- [ ] Create exec-plans/active/ directory (for component-specific exec-plans)
+- [ ] Create exec-plans/README.md with pointer to Platform guidance
+- [ ] Link to Platform exec-plans guidance
+- [ ] NO templates or detailed guidance (lives in Platform)
+
+### Phase 7: Ecosystem References
+- [ ] Create references/ecosystem.md
+- [ ] Link to Platform operator patterns
+- [ ] Link to Platform testing practices
+- [ ] Link to Platform security practices
+- [ ] Link to Platform Kubernetes/OpenShift fundamentals
+- [ ] Link to Platform cross-repo ADRs
+
+### Phase 8: Development & Testing Docs
+- [ ] Create [COMPONENT]_DEVELOPMENT.md using `templates/DEVELOPMENT-template.md`
+- [ ] Create [COMPONENT]_TESTING.md using `templates/TESTING-template.md`
+- [ ] Link to Platform for generic practices
+- [ ] Document ONLY component-specific details:
+  - Build instructions (make targets, go commands)
+  - Repository structure (cmd/, pkg/ organization)
+  - Development workflow (local dev, on-cluster testing)
+  - Test suites (unit, integration, E2E locations and commands)
+  - Component-specific test patterns
+  - Common development tasks (add CRD, add controller, update deps)
+
+### Phase 9: Validation
+- [ ] Run `bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH"` (includes link validation)
+- [ ] Verify AGENTS.md ≤100 lines
+- [ ] Verify no generic duplication
+- [ ] Verify ecosystem.md exists with Platform links
+- [ ] Verify all external links (HTTP/HTTPS) are valid
+- [ ] Verify all internal links (relative paths) are valid
+- [ ] Fix any broken links found
+
+**Link Validation**:
+- Automatically checks all HTTP/HTTPS links (with timeout and user agent)
+- Validates internal/relative links (file existence)
+- Flags known Platform planned links as "KNOWN BROKEN"
+- Use `VERBOSE=true bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH"` to see all links
+- Use `bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH" false` to skip link validation
+
+## AGENTS.md Requirements
+
+**Length**: 80-100 lines (strict limit)
+
+**Required Sections**:
+1. Component metadata (name, repository)
+2. Platform reference (link to ecosystem hub)
+3. Component purpose (what is it?)
+4. Core components (brief)
+5. Documentation structure (compressed)
+6. Knowledge graph (visual)
+7. Platform ecosystem links (operator patterns, testing, security, etc.)
+
+**Format**: Compressed, table-based, links not prose
+
+**Example**:
+```markdown
+# Component Name - Agentic Documentation
+
+**Component**: Machine Config Operator  
+**Repository**: openshift/machine-config-operator  
+
+> **Generic Platform Patterns**: See Platform documentation (openshift/enhancements/ai-docs/)
+
+## What is MCO?
+
+Manages OS configuration for OpenShift nodes. Controls everything between kernel and kubelet.
+
+## Core Components
+
+- **MCD**: DaemonSet applying configs | **MCC**: Coordinates upgrades | **MCS**: Serves Ignition
+
+## Documentation Structure
+
+```text
+ai-docs/
+├── domain/          # CRDs: MachineConfig, MachineConfigPool
+├── architecture/    # Component internals
+├── decisions/       # Component ADRs
+└── exec-plans/      # Feature planning
+```text
+
+## Platform Links
+
+**Patterns**: Operator | Testing | Security (see Platform docs)
+
+## Component-Specific Domain Concepts
+
+**Template**: `templates/domain-concept-template.md`
+
+**Structure**:
+- API Group / Kind / Scope
+- Purpose (component-specific behavior)
+- Key fields (most important only)
+- Lifecycle
+- Examples (component-specific usage)
+
+**Length**: 100-200 lines per concept
+
+**Example**: MachineConfig (MCO-specific)
+- Ignition config structure
+- Rendered config merging
+- OS update mechanism
+- Ownership model (system vs user)
+
+## Component Architecture
+
+**File**: `architecture/components.md`
+
+**Contents**:
+- Component structure (pkg/, cmd/, controllers/)
+- Component relationships
+- Data flow
+- Key responsibilities
+
+**Length**: 100-200 lines
+
+## Component ADRs
+
+**Format**: `decisions/adr-NNNN-title.md`
+
+**Example Component ADRs**:
+- Why rpm-ostree for OS updates (MCO)
+- Why Ignition format for config (MCO)
+- Why etcd for platform state (Platform, NOT component)
+
+**Template**: `decisions/adr-template.md`
+
+## Exec-Plans
+
+**Purpose**: Track active feature implementation (bridges enhancements and PRs)
+
+**Location**: Component repo (`ai-docs/exec-plans/active/`)
+
+**Guidance**: Lives in Platform documentation
+- **Templates & Usage**: See Platform exec-plans guidance
+- **Template**: `ai-docs/workflows/exec-plans/template.md`
+- **README**: `ai-docs/workflows/exec-plans/README.md`
+
+**Component repo structure**:
+```text
+ai-docs/exec-plans/
+├── active/           # Component-specific exec-plans go here
+└── README.md         # Pointer to Platform guidance
+```text
+
+**What component-docs creates**:
+- `active/` directory (empty, ready for exec-plans)
+- `README.md` with pointer to Platform
+
+**What component-docs does NOT create**:
+- ❌ Templates (live in Platform)
+- ❌ Detailed guidance (lives in Platform)
+- ❌ `completed/` directory (exec-plans are deleted after extracting knowledge)
+
+**Workflow**: See Platform exec-plans guidance
+
+## Ecosystem References
+
+**File**: `references/ecosystem.md`
+
+**Links to Platform**:
+- Operator patterns (controller-runtime, status conditions, webhooks, finalizers, RBAC)
+- Testing practices (pyramid, E2E framework)
+- Security practices (STRIDE, RBAC, secrets)
+- Reliability practices (SLO, observability, degraded states)
+- Kubernetes fundamentals (Pod, Node, DaemonSet)
+- OpenShift fundamentals (ClusterOperator, release image)
+- Cross-repo ADRs (etcd, CVO orchestration, immutable nodes)
+
+**Purpose**: Single source of truth for Platform links
+
+## Development & Testing Docs
+
+**Files**: `[COMPONENT]_DEVELOPMENT.md`, `[COMPONENT]_TESTING.md`
+
+**Templates**: Use `templates/DEVELOPMENT-template.md` and `templates/TESTING-template.md`
+
+### DEVELOPMENT.md Contents
+
+**Required sections** (component-specific ONLY):
+
+1. **Quick Start**
+   - Prerequisites (Go version, cluster access, tools)
+   - Build commands (`make [target]`, `go build`)
+   - Output locations
+
+2. **Repository Structure**
+   - cmd/ organization
+   - pkg/ organization
+   - manifests/ structure
+   - test/ organization
+
+3. **Development Workflow**
+   - Local development (build binaries, run tests)
+   - On-cluster testing (replace pod, run locally against cluster)
+   - Debugging (logs, exec, delve)
+
+4. **Code Organization**
+   - Where controllers live
+   - Where domain logic lives
+   - Package structure
+
+5. **Common Tasks**
+   - Add new CRD
+   - Add new controller
+   - Update dependencies
+   - Build & release process
+
+6. **Component-Specific Notes**
+   - Special build flags
+   - Environment variables
+   - Local development quirks
+
+**Link to Platform for**: Generic Go standards, controller-runtime patterns, CI/CD workflows
+
+### TESTING.md Contents
+
+**Required sections** (component-specific ONLY):
+
+1. **Test Organization**
+   - Test pyramid visualization
+   - Where tests live (unit, integration, E2E)
+
+2. **Unit Tests**
+   - Location (pkg/*/\*_test.go)
+   - Running commands (`make test-unit`, `go test`)
+   - Component-specific test patterns
+   - Coverage commands
+
+3. **Integration Tests**
+   - Location (test/integration/ or with build tags)
+   - Running commands
+   - Component-specific integration scenarios
+
+4. **E2E Tests**
+   - Location (test/e2e/)
+   - Running commands
+   - Component-specific E2E scenarios
+   - Test organization
+
+5. **Test Coverage**
+   - Current coverage
+   - Coverage targets
+   - Known gaps
+
+6. **Debugging Tests**
+   - Unit test failures
+   - E2E test failures
+   - Must-gather commands
+
+7. **Component-Specific Test Notes**
+   - Special test setup
+   - Known flaky tests
+   - Test environment requirements
+
+**Link to Platform for**: Test pyramid philosophy (60/30/10), E2E framework patterns, mock vs real strategies
+
+### Example from MCO
+
+**DEVELOPMENT.md** includes:
+- Build commands: `make machine-config-daemon`, `make machine-config-controller`
+- Repository structure: cmd/, pkg/, templates/, manifests/
+- Development workflow: Local build, on-cluster testing
+- Common tasks: Add CRD, update deps
+
+**TESTING.md** includes:
+- Unit test patterns: Controller tests, Ignition tests
+- Integration tests: Node update scenarios
+- E2E tests: OS update tests, config drift tests
+- Test commands: `make test-unit`, `make test-e2e`
+
+**Both files** are ~100-200 lines, lean, component-specific only
+
+## Validation Criteria
+
+✅ **AGENTS.md**:
+- At repo root (not in ai-docs/)
+- 80-100 lines
+- Compressed index format
+- Retrieval-first instruction
+- Platform ecosystem links section
+
+✅ **No duplication**:
+- No testing pyramid explanations
+- No controller-runtime patterns
+- No status condition semantics
+- No STRIDE threat model
+- No SLO framework
+
+✅ **Ecosystem references**:
+- references/ecosystem.md exists
+- Links to Platform operator patterns
+- Links to Platform testing practices
+- Links to Platform security practices
+
+✅ **Component-specific only**:
+- Domain concepts are component CRDs
+- ADRs are component-specific
+- Architecture is component internals
+
+✅ **Link validation**:
+- All external links (HTTP/HTTPS) return 200 OK
+- All internal links (relative paths) resolve to existing files/directories
+- No broken links except known Platform planned links
+- Links to upstream documentation are valid and current
+
+## Anti-Patterns
+
+### ❌ DON'T duplicate Platform content
+
+**Wrong**:
+```markdown
+# TESTING.md (187 lines, 60% generic)
+
+## Testing Pyramid
+[100 lines explaining pyramid]
+
+## Component Tests
+[37 lines component-specific]
+```text
+
+**Right**:
+```markdown
+# COMPONENT_TESTING.md (90 lines, 100% component-specific)
+
+> Testing practices: See Platform docs
+
+## Component Test Suites
+[90 lines component-specific]
+```text
+
+### ❌ DON'T explain generic patterns
+
+**Wrong**: Explaining controller-runtime in component docs  
+**Right**: Link to Platform, document component-specific usage
+
+### ❌ DON'T create cross-repo ADRs
+
+**Wrong**: ADR about etcd in component repo  
+**Right**: ADR about etcd in Platform
+
+## Metrics
+
+**Expected structure**:
+- AGENTS.md: 80-100 lines (vs 150+ for single-tier)
+- Total docs: ~2,500 lines (vs ~6,000 single-tier)
+- Generic duplication: 0 lines (vs ~2,400 single-tier)
+
+**Benefits**:
+- 58% smaller than single-tier
+- Zero duplication across ecosystem
+- Pattern updates: 1 Platform PR (not 60+ component PRs)
+
+## Prerequisites
+
+**Before running**:
+1. ✅ Platform exists at openshift/enhancements/ai-docs/
+2. ✅ Repository is OpenShift component
+3. ✅ You understand two-tier architecture
+4. ✅ Platform documentation exists at openshift/enhancements/ai-docs/
+
+## Arguments
+
+```bash
+/component-docs [--path <repository-path>]
+```text
+
+**Arguments**:
+- `--path <repository-path>`: Path to component repository (default: current directory)
+- No args: Create documentation in current directory
+
+## Success Output
+
+```text
+✅ Component Documentation Created
+
+Component: machine-config-operator
+Repository: /path/to/repo
+
+Structure:
+  ✅ AGENTS.md (root): 87 lines (target: 80-100)
+  ✅ Domain concepts: 4 files (component CRDs only)
+  ✅ Architecture: 1 file (components.md)
+  ✅ Component ADRs: 3 files
+  ✅ Exec-plans: README.md, active/
+  ✅ Ecosystem references: ecosystem.md with Platform links
+  ✅ Development: COMPONENT_DEVELOPMENT.md
+  ✅ Testing: COMPONENT_TESTING.md
+
+Validation:
+  ✅ AGENTS.md at root (80-100 lines)
+  ✅ No generic duplication
+  ✅ Platform links present
+  ✅ Component-specific content only
+
+Platform Links:
+  - Ecosystem hub: openshift/enhancements/ai-docs
+  - Operator patterns: 6 links
+  - Testing practices: 3 links
+  - Security practices: 2 links
+  - Kubernetes/OpenShift fundamentals: 8 links
+
+Next Steps:
+  1. Populate domain/*.md with component CRDs
+  2. Document architecture in components.md
+  3. Create component-specific ADRs
+  4. Use exec-plans/ for active features
+```text
+
+## Example: Machine Config Operator
+
+**Created files**:
+- AGENTS.md (87 lines)
+- ai-docs/domain/machineconfig.md
+- ai-docs/domain/machineconfigpool.md
+- ai-docs/domain/kubeletconfig.md
+- ai-docs/domain/containerruntimeconfig.md
+- ai-docs/architecture/components.md
+- ai-docs/decisions/adr-0001-rpm-ostree-updates.md
+- ai-docs/decisions/adr-0002-ignition-format.md
+- ai-docs/decisions/adr-0003-config-drift-detection.md
+- ai-docs/references/ecosystem.md
+- ai-docs/exec-plans/README.md
+- ai-docs/MCO_DEVELOPMENT.md
+- ai-docs/MCO_TESTING.md
+
+**Total**: ~2,500 lines (component-specific only)
+
+## See Also
+
+- `/update-platform-docs` - Update Platform documentation
+- Platform Documentation (openshift/enhancements/ai-docs/)
+- [MCO Example](https://github.com/openshift/machine-config-operator/tree/master/ai-docs)
diff --git a/plugins/agentic-docs/skills/component-docs/scripts/create-structure.sh b/plugins/agentic-docs/skills/component-docs/scripts/create-structure.sh
new file mode 100755
index 000000000..681ab6061
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/scripts/create-structure.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+set -euo pipefail
+
+REPO_PATH="${1:-.}"
+
+echo "📁 Creating component documentation structure in: $REPO_PATH"
+
+# Create directory structure
+mkdir -p "$REPO_PATH/ai-docs/domain"
+mkdir -p "$REPO_PATH/ai-docs/architecture"
+mkdir -p "$REPO_PATH/ai-docs/decisions"
+mkdir -p "$REPO_PATH/ai-docs/exec-plans/active"
+mkdir -p "$REPO_PATH/ai-docs/exec-plans/completed"
+mkdir -p "$REPO_PATH/ai-docs/references"
+
+echo "✅ Directory structure created:"
+tree -L 3 "$REPO_PATH/ai-docs" 2>/dev/null || find "$REPO_PATH/ai-docs" -type d
+
+echo ""
+echo "Next: LLM creates documentation files based on SKILL.md"
diff --git a/plugins/agentic-docs/skills/component-docs/scripts/validate.sh b/plugins/agentic-docs/skills/component-docs/scripts/validate.sh
new file mode 100755
index 000000000..549124704
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/scripts/validate.sh
@@ -0,0 +1,353 @@
+#!/bin/bash
+#
+# Component Documentation Validator
+#
+# Validates component-level documentation structure and links.
+#
+# Usage:
+#   ./validate.sh [REPO_PATH] [VALIDATE_LINKS]
+#
+# Arguments:
+#   REPO_PATH        Path to repository (default: current directory)
+#   VALIDATE_LINKS   true/false to enable/disable link validation (default: true)
+#
+# Environment:
+#   VERBOSE=true     Show all successful links (default: false, only shows broken links)
+#
+# Examples:
+#   ./validate.sh                          # Validate current directory with link checking
+#   ./validate.sh /path/to/repo false      # Validate without link checking
+#   VERBOSE=true ./validate.sh             # Show all links, including successful ones
+#
+set -euo pipefail
+
+REPO_PATH="${1:-.}"
+VALIDATE_LINKS="${2:-true}"  # Default: validate links
+VERBOSE="${VERBOSE:-false}"   # Set VERBOSE=true to see all successful links
+
+echo "✅ Validating component documentation in: $REPO_PATH"
+echo ""
+
+# Function to validate internal/relative links
+validate_internal_links() {
+    local file_path=$1
+    local file_dir=$(dirname "$file_path")
+    local links_found=false
+    local broken_links=false
+    local total_links=0
+    local valid_links=0
+    local invalid_links=0
+
+    # Extract markdown links: [text](url)
+    # Match relative paths (not starting with http:// or https://)
+    while IFS= read -r link; do
+        links_found=true
+        ((total_links++))
+
+        # Skip anchors (links starting with #)
+        if [[ "$link" =~ ^# ]]; then
+            ((valid_links++))
+            continue
+        fi
+
+        # Resolve relative path
+        local resolved_path
+        if [[ "$link" =~ ^/ ]]; then
+            # Absolute path from repo root
+            resolved_path="$REPO_PATH$link"
+        else
+            # Relative path from current file
+            resolved_path="$file_dir/$link"
+        fi
+
+        # Remove anchor if present (e.g., file.md#section)
+        resolved_path="${resolved_path%%#*}"
+
+        # Check if file exists
+        if [ -f "$resolved_path" ] || [ -d "$resolved_path" ]; then
+            ((valid_links++))
+            if [ "${VERBOSE:-false}" = "true" ]; then
+                echo "  ✅ OK: $link"
+            fi
+        else
+            ((invalid_links++))
+            echo "  ❌ NOT FOUND: $link (resolved to: $resolved_path)"
+            broken_links=true
+        fi
+    done < <(grep -oP '\[([^\]]+)\]\(\K([^)]+)(?=\))' "$file_path" 2>/dev/null | grep -v '^https\?://' || true)
+
+    if [ "$links_found" = false ]; then
+        echo "  ℹ️  No internal links found"
+    else
+        echo "  📊 Internal links: $total_links total, $valid_links valid, $invalid_links invalid"
+    fi
+
+    if [ "$broken_links" = true ]; then
+        return 1
+    fi
+    return 0
+}
+
+# Function to remove broken link from file
+remove_broken_link() {
+    local file_path=$1
+    local broken_url=$2
+
+    # Escape special characters in URL for sed/grep
+    local escaped_url=$(printf '%s\n' "$broken_url" | sed 's/[[\.*^$/]/\\&/g')
+
+    # Remove entire line containing the broken link
+    sed -i "\|$escaped_url|d" "$file_path"
+
+    echo "  🔧 REMOVED line containing broken link: $broken_url"
+}
+
+# Function to clean up empty sections after link removal
+cleanup_empty_sections() {
+    local file_path=$1
+    local cleaned=false
+
+    # Remove empty markdown tables (header + separator with no data rows)
+    # Matches: | Header | ... |\n|--------|-----|  followed by blank line or new section
+    python3 -c "
+import re
+with open('$file_path', 'r') as f:
+    content = f.read()
+# Match table header + separator with optional blank lines but no data rows
+# Pattern: table header, separator, then either EOF, blank line + header, or just header
+content = re.sub(r'\|[^\n]+\|\n\|[-:| ]+\|\n+(?=##|\Z)', '', content)
+with open('$file_path', 'w') as f:
+    f.write(content)
+" && cleaned=true
+
+    # Remove multiple consecutive blank lines (reduce to max 2)
+    perl -i -0pe 's/\n{3,}/\n\n/g' "$file_path"
+
+    # Remove section headers that have no content before next header
+    # Pattern: ## Header\n\n## Another Header -> ## Another Header
+    sed -i '/^##[^#]/ { N; s/^##[^#][^\n]*\n\n##/##/; }' "$file_path"
+
+    if [ "$cleaned" = true ]; then
+        echo "  🧹 Cleaned up empty sections"
+    fi
+}
+
+# Function to validate HTTP/HTTPS links
+validate_links() {
+    local file_path=$1
+    local links_found=false
+    local broken_links=false
+    local total_links=0
+    local valid_links=0
+    local invalid_links=0
+    local links_to_remove=()
+
+    # Extract markdown links: [text](url)
+    # Match http:// and https:// URLs only
+    while IFS= read -r link; do
+        links_found=true
+        ((total_links++))
+
+        # Mark known sites that block curl but are valid
+        local is_curl_blocked=false
+        if [[ "$link" =~ "docs.openshift.com" ]]; then
+            is_curl_blocked=true
+        fi
+
+        # Check if URL is accessible (with timeout and follow redirects)
+        # Add user agent to avoid some sites blocking curl
+        http_code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 -L \
+            -A "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36" \
+            "$link" 2>/dev/null || echo "000")
+
+        # Small delay to avoid rate limiting
+        sleep 0.1
+
+        if [[ "$http_code" == "200" ]]; then
+            ((valid_links++))
+            if [ "${VERBOSE:-false}" = "true" ]; then
+                echo "  ✅ OK ($http_code): $link"
+            fi
+        elif [[ "$http_code" =~ ^0+$ ]]; then
+            ((invalid_links++))
+            echo "  ❌ TIMEOUT/ERROR: $link"
+            links_to_remove+=("$link")
+            broken_links=true
+        elif [[ "$http_code" == "404" ]]; then
+            ((invalid_links++))
+            echo "  ❌ NOT FOUND ($http_code): $link"
+            links_to_remove+=("$link")
+            broken_links=true
+        elif [[ "$http_code" == "403" ]]; then
+            if [ "$is_curl_blocked" = true ]; then
+                ((valid_links++))
+                if [ "${VERBOSE:-false}" = "true" ]; then
+                    echo "  ⚠️  OK (site blocks curl, assume valid): $link"
+                fi
+            else
+                ((invalid_links++))
+                echo "  ❌ FORBIDDEN ($http_code): $link"
+                links_to_remove+=("$link")
+                broken_links=true
+            fi
+        else
+            ((invalid_links++))
+            echo "  ❌ BROKEN ($http_code): $link"
+            links_to_remove+=("$link")
+            broken_links=true
+        fi
+    done < <(grep -oP '\[([^\]]+)\]\(\K(https?://[^)]+)' "$file_path" 2>/dev/null || true)
+
+    if [ "$links_found" = false ]; then
+        echo "  ℹ️  No HTTP/HTTPS links found"
+    else
+        echo "  📊 Links: $total_links total, $valid_links valid, $invalid_links invalid"
+    fi
+
+    # Remove broken links from the file
+    if [ ${#links_to_remove[@]} -gt 0 ]; then
+        echo "  🔧 Removing ${#links_to_remove[@]} broken link(s) from file..."
+        for broken_link in "${links_to_remove[@]}"; do
+            remove_broken_link "$file_path" "$broken_link"
+        done
+        # Clean up empty sections after removing links
+        cleanup_empty_sections "$file_path"
+    fi
+
+    if [ "$broken_links" = true ]; then
+        return 1
+    fi
+    return 0
+}
+
+# Check AGENTS.md at root
+if [ ! -f "$REPO_PATH/AGENTS.md" ]; then
+    echo "❌ AGENTS.md not found at repository root"
+    exit 1
+fi
+
+LINE_COUNT=$(wc -l < "$REPO_PATH/AGENTS.md")
+echo "  ✅ AGENTS.md exists"
+if [ "$LINE_COUNT" -lt 80 ] || [ "$LINE_COUNT" -gt 100 ]; then
+    echo "  ⚠️  AGENTS.md is $LINE_COUNT lines (target: 80-100)"
+else
+    echo "     $LINE_COUNT lines (target: 80-100) ✅"
+fi
+
+# Check for Platform references
+if grep -q "Platform" "$REPO_PATH/AGENTS.md" || grep -q "openshift/enhancements" "$REPO_PATH/AGENTS.md"; then
+    echo "  ✅ Platform ecosystem references found"
+else
+    echo "  ⚠️  No Platform ecosystem references found"
+fi
+
+# Check for retrieval-first instruction
+if grep -q -i "retrieval" "$REPO_PATH/AGENTS.md"; then
+    echo "  ✅ Retrieval-first instruction found"
+else
+    echo "  ⚠️  No retrieval-first instruction"
+fi
+
+echo ""
+
+# Check required directories
+for dir in domain architecture decisions exec-plans references; do
+    if [ -d "$REPO_PATH/ai-docs/$dir" ]; then
+        echo "  ✅ ai-docs/$dir/ exists"
+    else
+        echo "  ❌ ai-docs/$dir/ missing"
+    fi
+done
+
+echo ""
+
+# Check ecosystem.md
+if [ -f "$REPO_PATH/ai-docs/references/ecosystem.md" ]; then
+    echo "  ✅ references/ecosystem.md exists"
+    if grep -q "Platform" "$REPO_PATH/ai-docs/references/ecosystem.md"; then
+        echo "     Contains Platform links ✅"
+    else
+        echo "     ⚠️  No Platform links found"
+    fi
+else
+    echo "  ⚠️  references/ecosystem.md missing"
+fi
+
+echo ""
+
+# Check for forbidden patterns (generic content duplication)
+echo "Checking for generic duplication..."
+
+FORBIDDEN_PATTERNS=(
+    "testing pyramid"
+    "controller-runtime reconciliation"
+    "Available/Progressing/Degraded conditions"
+    "STRIDE threat model"
+    "SLO error budget"
+)
+
+FOUND_DUPLICATION=false
+for pattern in "${FORBIDDEN_PATTERNS[@]}"; do
+    if grep -riq "$pattern" "$REPO_PATH/ai-docs/" 2>/dev/null; then
+        echo "  ⚠️  Found generic pattern: '$pattern' (should link to Platform)"
+        FOUND_DUPLICATION=true
+    fi
+done
+
+if [ "$FOUND_DUPLICATION" = false ]; then
+    echo "  ✅ No generic duplication detected"
+fi
+
+echo ""
+
+# Validate links (if enabled)
+if [ "$VALIDATE_LINKS" = "true" ]; then
+    echo "Validating links..."
+    echo ""
+
+    LINK_VALIDATION_FAILED=false
+
+    # Check links in AGENTS.md
+    if [ -f "$REPO_PATH/AGENTS.md" ]; then
+        echo "📄 Checking AGENTS.md:"
+        echo "  🔗 External links:"
+        if ! validate_links "$REPO_PATH/AGENTS.md"; then
+            LINK_VALIDATION_FAILED=true
+        fi
+        echo "  🔗 Internal links:"
+        if ! validate_internal_links "$REPO_PATH/AGENTS.md"; then
+            LINK_VALIDATION_FAILED=true
+        fi
+        echo ""
+    fi
+
+    # Check links in all ai-docs markdown files
+    if [ -d "$REPO_PATH/ai-docs" ]; then
+        while IFS= read -r -d '' file; do
+            echo "📄 Checking $(basename "$file"):"
+            echo "  🔗 External links:"
+            if ! validate_links "$file"; then
+                LINK_VALIDATION_FAILED=true
+            fi
+            echo "  🔗 Internal links:"
+            if ! validate_internal_links "$file"; then
+                LINK_VALIDATION_FAILED=true
+            fi
+            echo ""
+        done < <(find "$REPO_PATH/ai-docs" -name "*.md" -type f -print0)
+    fi
+
+    if [ "$LINK_VALIDATION_FAILED" = true ]; then
+        echo "⚠️  Some links are broken or inaccessible"
+        echo ""
+        echo "To skip link validation, run: $0 $REPO_PATH false"
+    else
+        echo "✅ All links validated successfully"
+    fi
+else
+    echo "ℹ️  Link validation skipped (run with 'true' as 2nd arg to enable)"
+fi
+
+echo ""
+echo "==================================="
+echo "✅ Validation complete"
diff --git a/plugins/agentic-docs/skills/component-docs/templates/AGENTS-template.md b/plugins/agentic-docs/skills/component-docs/templates/AGENTS-template.md
new file mode 100644
index 000000000..a1e328964
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/templates/AGENTS-template.md
@@ -0,0 +1,62 @@
+# Component Name - Agentic Documentation
+
+**Component**: [Component Full Name]  
+**Repository**: openshift/[repo-name]  
+
+> **Generic Platform Patterns**: See Platform documentation (openshift/enhancements/ai-docs/) for operator patterns, testing practices, security guidelines, and cross-repo ADRs.
+
+## What is [Component Name]?
+
+[Brief 1-2 sentence description of what the component does]
+
+**Key Principle**: [Core principle or design philosophy]
+
+## Core Components
+
+- **Component1**: Purpose | **Component2**: Purpose | **Component3**: Purpose
+
+**Quick Start**: `oc describe clusteroperator/[name]` | `oc describe [primary-resource]`
+
+## Documentation Structure
+
+```text
+ai-docs/
+├── domain/                    # Component-specific CRDs
+├── architecture/              # Component internals
+├── decisions/                 # Component-specific ADRs
+├── exec-plans/                # Feature planning
+├── references/
+│   └── ecosystem.md           # Links to Platform
+├── [COMPONENT]_DEVELOPMENT.md # Component dev workflows
+└── [COMPONENT]_TESTING.md     # Component test suites
+```text
+
+**Exec-Plans**: Use `active/` for new features. See [Platform Exec-Plans Guide](Platform documentation).
+
+**Platform Patterns (Platform)**: [Operator](Platform documentation) | [Testing](Platform documentation) | [Security](Platform documentation)
+
+## Knowledge Graph
+
+```text
+                         [AGENTS.md] ← Start here
+                              │
+              ┌───────────────┼───────────────┐
+              │               │               │
+         [domain/]      [architecture/]  [decisions/]
+        CRD concepts    Component design  ADR history
+              │               │               │
+              └───────────────┼───────────────┘
+                              │
+                      [references/ecosystem]
+                      Links to Platform
+```text
+
+**AI Agent Path**: domain/ → architecture/ → decisions/ → [COMPONENT]_DEVELOPMENT.md
+
+## External References
+
+- [Product Docs](https://docs.openshift.com/) | [Related Project](https://github.com/...)
+
+---
+
+**Platform Documentation**: openshift/enhancements/ai-docs/
diff --git a/plugins/agentic-docs/skills/component-docs/templates/DEVELOPMENT-template.md b/plugins/agentic-docs/skills/component-docs/templates/DEVELOPMENT-template.md
new file mode 100644
index 000000000..3077eb84c
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/templates/DEVELOPMENT-template.md
@@ -0,0 +1,199 @@
+# [Component Name] - Development Guide
+
+> **Generic Development Practices**: See [Platform Development Practices](Platform documentation) for Go standards, controller-runtime patterns, and CI/CD workflows.
+
+This guide covers **[COMPONENT]-specific** development practices.
+
+## Quick Start
+
+### Prerequisites
+
+- Go 1.22+ (check go.mod for exact version)
+- Access to OpenShift cluster
+- `KUBECONFIG` environment variable set
+- Container build tool (Podman or Docker)
+
+### Build Binaries
+
+```bash
+# Build component
+make [component-name]
+
+# Build all binaries
+make binaries
+
+# Or use go directly
+go build -o _output/[binary-name] ./cmd/[component]
+```text
+
+**Binaries output**: `./_output/linux/amd64/` or `./bin/`
+
+## Repository Structure
+
+```text
+cmd/                           # Binary entrypoints
+├── [component-1]/             # Component 1
+└── [component-2]/             # Component 2
+
+pkg/
+├── controller/                # Controllers
+│   ├── [controller-1]/        # Controller 1
+│   └── [controller-2]/        # Controller 2
+├── [domain-logic]/            # Domain-specific logic
+└── [utilities]/               # Utilities
+
+manifests/                     # Deployment manifests
+├── [component-1]/             # Component 1 deployment
+└── [component-2]/             # Component 2 deployment
+
+test/
+├── e2e/                       # End-to-end tests
+└── integration/               # Integration tests
+```text
+
+## Development Workflow
+
+### 1. Local Development
+
+Edit code, build binaries locally:
+
+```bash
+make [component-name]
+```text
+
+Run unit tests:
+
+```bash
+make test-unit
+
+# Or specific package
+go test -v ./pkg/[package]/...
+```text
+
+### 2. Testing on Cluster
+
+**Option A: Replace running pod**
+
+```bash
+# Build image
+make image
+
+# Push to registry
+podman push localhost/[component]:latest quay.io/[user]/[component]:dev
+
+# Update deployment to use dev image
+oc set image deployment/[component] [container]=[image]:dev -n [namespace]
+```text
+
+**Option B: Run locally against cluster**
+
+```bash
+# Port-forward if needed
+oc port-forward svc/[service] 8443:8443 -n [namespace]
+
+# Run binary with KUBECONFIG
+./_output/[binary] --kubeconfig=$KUBECONFIG
+```text
+
+### 3. Debugging
+
+**View logs**:
+```bash
+oc logs -f deployment/[component] -n [namespace]
+```text
+
+**Exec into pod**:
+```bash
+oc exec -it deployment/[component] -n [namespace] -- /bin/bash
+```text
+
+**Debug with delve**:
+```bash
+# Build with debug symbols
+go build -gcflags="all=-N -l" -o _output/[binary] ./cmd/[component]
+
+# Run with delve
+dlv exec ./_output/[binary]
+```text
+
+## Code Organization
+
+### Controllers
+
+Location: `pkg/controller/[name]/`
+
+**Pattern**:
+- `controller.go` - Controller setup, watches
+- `reconcile.go` - Reconcile logic
+- `*_test.go` - Unit tests
+
+**Generic controller patterns**: See [Platform](Platform documentation)
+
+### Domain Logic
+
+Location: `pkg/[domain]/`
+
+Document component-specific business logic here.
+
+## Common Tasks
+
+### Add New CRD
+
+1. Define types in `pkg/apis/[group]/[version]/types.go`
+2. Run `make manifests` to generate CRD YAML
+3. Update RBAC in `manifests/*/rbac.yaml`
+4. Create controller in `pkg/controller/[name]/`
+5. Register controller in `cmd/[component]/main.go`
+
+### Add New Controller
+
+1. Create `pkg/controller/[name]/controller.go`
+2. Implement `Reconcile()` function
+3. Register in main.go
+4. Add unit tests
+5. Add E2E tests
+
+### Update Dependencies
+
+```bash
+# Update specific dependency
+go get [module]@[version]
+
+# Update all dependencies
+go get -u ./...
+
+# Tidy and vendor
+go mod tidy
+go mod vendor
+```text
+
+## Build & Release
+
+### Local Build
+
+```bash
+make image
+```text
+
+### CI Build
+
+Component images are built by OpenShift CI on PR merge. See `.ci-operator.yaml`.
+
+### Release Process
+
+Component is released as part of OpenShift release image. See [Platform Release Process](Platform documentation).
+
+## Component-Specific Notes
+
+[Add component-specific development notes here]
+
+- Special build flags
+- Environment variables
+- Local development quirks
+- Common gotchas
+
+## See Also
+
+- [Testing Guide](./[COMPONENT]_TESTING.md)
+- [Architecture](./architecture/components.md)
+- [Platform Development Practices](Platform documentation)
diff --git a/plugins/agentic-docs/skills/component-docs/templates/TESTING-template.md b/plugins/agentic-docs/skills/component-docs/templates/TESTING-template.md
new file mode 100644
index 000000000..f91ad2169
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/templates/TESTING-template.md
@@ -0,0 +1,297 @@
+# [Component Name] - Testing Guide
+
+> **Generic Testing Practices**: See [Platform Testing Practices](Platform documentation) for test pyramid philosophy (60/30/10), E2E framework patterns, and mock vs real strategies.
+
+This guide covers **[COMPONENT]-specific** test suites and testing practices.
+
+## Test Organization
+
+The component follows the standard testing pyramid:
+
+```text
+        E2E Tests (10%, slow, comprehensive)
+              ▲
+         Integration Tests (30%, medium)
+              ▲
+          Unit Tests (60%, fast, focused)
+```text
+
+## Unit Tests
+
+### Location
+
+Unit tests live alongside the code they test:
+- `pkg/controller/*/` - Controller unit tests
+- `pkg/[domain]/*/` - Domain logic unit tests
+
+### Running Unit Tests
+
+```bash
+# All unit tests
+make test-unit
+
+# Specific package
+go test -v ./pkg/[package]/...
+
+# Disable caching
+go test -count=1 ./pkg/...
+
+# With coverage
+go test -cover ./pkg/...
+
+# Coverage report
+go test -coverprofile=coverage.out ./pkg/...
+go tool cover -html=coverage.out
+```text
+
+### Unit Test Patterns
+
+#### Controller Tests
+
+Test controller logic without real Kubernetes API:
+
+```go
+func TestReconcile(t *testing.T) {
+    // Use fake clientset
+    client := fake.NewSimpleClientset()
+    
+    // Create test objects
+    obj := &v1.MyResource{...}
+    
+    // Create reconciler
+    r := &Reconciler{Client: client}
+    
+    // Test reconcile logic
+    result, err := r.Reconcile(ctx, req)
+    require.NoError(t, err)
+    assert.False(t, result.Requeue)
+}
+```text
+
+**For generic controller patterns**, see [Platform Controller Runtime](Platform documentation)
+
+#### Domain Logic Tests
+
+Test business logic:
+
+```go
+func TestDomainFunction(t *testing.T) {
+    input := createTestInput()
+    
+    result, err := processInput(input)
+    require.NoError(t, err)
+    assert.Equal(t, expectedOutput, result)
+}
+```text
+
+### Component-Specific Unit Test Patterns
+
+[Document component-specific unit test patterns here]
+
+Example:
+- How to mock component-specific interfaces
+- How to test component-specific algorithms
+- How to test component-specific validation logic
+
+## Integration Tests
+
+### Location
+
+`test/integration/` or alongside unit tests with build tag:
+
+```go
+//go:build integration
+// +build integration
+```text
+
+### Running Integration Tests
+
+```bash
+# Requires KUBECONFIG set to test cluster
+make test-integration
+
+# Or with build tag
+go test -v -tags=integration ./test/integration/...
+```text
+
+### Integration Test Patterns
+
+Test with real or envtest Kubernetes API:
+
+```go
+func TestControllerIntegration(t *testing.T) {
+    // Use envtest or real cluster client
+    client := setupTestCluster(t)
+    
+    // Create real objects
+    obj := &v1.MyResource{...}
+    err := client.Create(ctx, obj)
+    require.NoError(t, err)
+    
+    // Wait for reconciliation
+    eventually.Assert(t, func() bool {
+        err := client.Get(ctx, key, obj)
+        return err == nil && obj.Status.Phase == "Ready"
+    }, 30*time.Second)
+}
+```text
+
+### Component-Specific Integration Tests
+
+[Document component-specific integration test scenarios]
+
+Example:
+- Test CRD validation webhooks
+- Test multi-resource workflows
+- Test component-to-component interactions
+
+## E2E Tests
+
+### Location
+
+`test/e2e/`
+
+### Running E2E Tests
+
+```bash
+# Requires real OpenShift cluster
+export KUBECONFIG=/path/to/kubeconfig
+make test-e2e
+
+# Or specific test
+go test -v ./test/e2e/ -run TestSpecificScenario -timeout 30m
+```text
+
+### E2E Test Organization
+
+```text
+test/e2e/
+├── [feature-1]_test.go        # Feature 1 E2E tests
+├── [feature-2]_test.go        # Feature 2 E2E tests
+└── framework/                 # E2E test utilities
+    ├── client.go              # K8s client helpers
+    └── helpers.go             # Test helpers
+```text
+
+### E2E Test Patterns
+
+Test end-user scenarios:
+
+```go
+func TestFeatureE2E(t *testing.T) {
+    // Setup
+    client := framework.NewClient(t)
+    
+    // Create resource
+    resource := &v1.MyResource{
+        Spec: v1.MyResourceSpec{...},
+    }
+    err := client.Create(ctx, resource)
+    require.NoError(t, err)
+    
+    // Wait for expected state
+    err = wait.PollImmediate(5*time.Second, 5*time.Minute, func() (bool, error) {
+        err := client.Get(ctx, key, resource)
+        if err != nil {
+            return false, err
+        }
+        return resource.Status.Phase == "Ready", nil
+    })
+    require.NoError(t, err)
+    
+    // Verify side effects
+    verify.SideEffects(t, client, resource)
+    
+    // Cleanup
+    defer client.Delete(ctx, resource)
+}
+```text
+
+**For generic E2E patterns**, see [Platform E2E Framework](Platform documentation)
+
+### Component-Specific E2E Scenarios
+
+[Document component-specific E2E test scenarios]
+
+Example:
+- Happy path scenarios
+- Upgrade scenarios
+- Failure recovery scenarios
+- Multi-resource workflows
+
+## Test Coverage
+
+### Current Coverage
+
+```bash
+# Generate coverage report
+make coverage
+
+# Expected coverage targets:
+# - Unit tests: 60-80%
+# - Integration tests: Critical paths
+# - E2E tests: User-facing scenarios
+```text
+
+### Coverage Gaps
+
+[Document known coverage gaps and plans to address them]
+
+## CI/CD Testing
+
+### PR Testing
+
+CI runs on every PR:
+- Unit tests (always)
+- Integration tests (if applicable)
+- E2E tests (critical scenarios)
+
+See `.ci-operator.yaml` for CI configuration.
+
+### Periodic Testing
+
+Periodic jobs run full E2E suite:
+- Upgrade tests
+- Stress tests
+- Long-running tests
+
+## Debugging Failing Tests
+
+### Unit Test Failures
+
+```bash
+# Run with verbose output
+go test -v ./pkg/[package]/... -run TestSpecific
+
+# Run with race detector
+go test -race ./pkg/...
+```text
+
+### E2E Test Failures
+
+```bash
+# Check must-gather
+oc adm must-gather
+
+# Check operator logs
+oc logs -n [namespace] deployment/[component]
+
+# Check resource status
+oc get [resource] -o yaml
+```text
+
+## Component-Specific Test Notes
+
+[Add component-specific testing notes]
+
+Example:
+- Special test setup requirements
+- Known flaky tests
+- Test environment requirements
+- Common test failures and solutions
+
+## See Also
+
+- [Development Guide](./[COMPONENT]_DEVELOPMENT.md)
+- [Architecture](./architecture/components.md)
+- [Platform Testing Practices](Platform documentation)
diff --git a/plugins/agentic-docs/skills/component-docs/templates/adr-template.md b/plugins/agentic-docs/skills/component-docs/templates/adr-template.md
new file mode 100644
index 000000000..ce1338d2d
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/templates/adr-template.md
@@ -0,0 +1,50 @@
+# ADR-NNNN: Title
+
+**Status**: Proposed | Accepted | Deprecated | Superseded  
+**Date**: YYYY-MM-DD  
+**Deciders**: Team or individuals  
+**Component**: [Component Name]
+
+## Context
+
+What is the component-specific issue or situation we're addressing?
+
+**Scope**: This ADR is component-specific. For cross-repo decisions, see [Platform ADRs](Platform documentation).
+
+## Decision
+
+What component-specific decision did we make?
+
+## Rationale
+
+Why did we choose this approach for this component?
+
+## Consequences
+
+### Positive
+- Benefit 1 (component-specific)
+- Benefit 2 (component-specific)
+
+### Negative
+- Trade-off 1 (component-specific)
+- Trade-off 2 (component-specific)
+
+### Neutral
+- Implication 1
+
+## Alternatives Considered
+
+### Alternative 1
+**Description**: ...  
+**Rejected because**: ...
+
+### Alternative 2
+**Description**: ...  
+**Rejected because**: ...
+
+## References
+
+- Related component docs
+- Related ADRs
+- External sources
+- [Platform ADRs](Platform documentation) for cross-repo decisions
diff --git a/plugins/agentic-docs/skills/component-docs/templates/domain-concept-template.md b/plugins/agentic-docs/skills/component-docs/templates/domain-concept-template.md
new file mode 100644
index 000000000..11c3f33f7
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/templates/domain-concept-template.md
@@ -0,0 +1,63 @@
+# ResourceName
+
+**API Group**: `group.openshift.io/v1`  
+**Kind**: `ResourceName`  
+**Scope**: Cluster | Namespaced
+
+## Purpose
+
+[Brief description of what this resource does - component-specific behavior only]
+
+**Key Principle**: [Core principle specific to this resource]
+
+## Spec Structure
+
+```go
+type ResourceNameSpec struct {
+    Field1 Type  // Description
+    Field2 Type  // Description
+    Field3 Type  // Description
+}
+```text
+
+## Key Concepts
+
+### Concept 1
+
+[Component-specific behavior and semantics]
+
+### Concept 2
+
+[Component-specific patterns and usage]
+
+## Lifecycle
+
+1. **Creation**: [What happens when created]
+2. **Update**: [How updates are handled]
+3. **Deletion**: [Cleanup behavior]
+
+## Example: Common Use Case
+
+```yaml
+apiVersion: group.openshift.io/v1
+kind: ResourceName
+metadata:
+  name: example
+spec:
+  field1: value
+  field2: value
+```text
+
+**Use case**: [When to use this pattern]
+
+## Component-Specific Behavior
+
+[Document ONLY component-specific behavior, not generic patterns]
+
+**For generic patterns**, see:
+- Controller patterns: [Platform](Platform documentation)
+- Status conditions: [Platform](Platform documentation)
+
+## Related Concepts
+
+- [Other Resource](./other-resource.md) - Related component resource
diff --git a/plugins/agentic-docs/skills/component-docs/templates/ecosystem-template.md b/plugins/agentic-docs/skills/component-docs/templates/ecosystem-template.md
new file mode 100644
index 000000000..b52ddbe30
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/templates/ecosystem-template.md
@@ -0,0 +1,83 @@
+# Platform Ecosystem References
+
+This document links to generic OpenShift/Kubernetes patterns in the Platform ecosystem hub. The component inherits these platform-wide patterns and practices.
+
+## Operator Patterns
+
+**Location**: [ai-docs/platform/operator-patterns/](Platform documentation)
+
+- **Controller Runtime**: Reconciliation loops, event handling, client patterns
+- **Status Conditions**: Available, Progressing, Degraded condition semantics
+- **Webhooks**: Validation and mutation patterns
+- **Finalizers**: Resource cleanup patterns
+- **RBAC**: Service account and permissions
+
+**Component Usage**:
+- [Describe how this component uses these patterns]
+
+## Testing Practices
+
+**Location**: [ai-docs/practices/testing/](Platform documentation)
+
+- **Test Pyramid**: Unit > Integration > E2E ratio (60/30/10)
+- **E2E Framework**: OpenShift E2E test patterns
+
+**Component Usage**:
+- See `[COMPONENT]_TESTING.md` for component-specific test suites
+
+## Security Practices
+
+**Location**: [ai-docs/practices/security/](Platform documentation)
+
+- **STRIDE Threat Model**: Threat modeling framework
+- **RBAC Guidelines**: Role and ClusterRole design
+
+**Component Usage**:
+- [Describe component-specific security considerations]
+
+## Reliability Practices
+
+**Location**: [ai-docs/practices/reliability/](Platform documentation)
+
+- **SLO Framework**: Service Level Objectives and error budgets
+- **Observability**: Metrics, logging, tracing patterns
+
+**Component Usage**:
+- [Describe component-specific reliability patterns]
+
+## Kubernetes Fundamentals
+
+**Location**: [ai-docs/domain/kubernetes/](Platform documentation)
+
+- **Pod**: Pod lifecycle, container specs
+- **CRDs**: CustomResourceDefinition patterns
+
+**Component Usage**:
+- [Describe how component uses Kubernetes fundamentals]
+
+## OpenShift Fundamentals
+
+**Location**: [ai-docs/domain/openshift/](Platform documentation)
+
+- **ClusterOperator**: Cluster operator status reporting
+- **ClusterVersion**: Platform upgrade orchestration
+
+**Component Usage**:
+- [Describe how component integrates with platform]
+
+## Cross-Repository ADRs
+
+**Location**: [ai-docs/decisions/](Platform documentation)
+
+Platform-wide architectural decisions:
+- **etcd Backend**: Why etcd is used for Kubernetes state
+- **CVO Orchestration**: Why CVO orchestrates upgrades
+- **Immutable Nodes**: Why RHCOS + rpm-ostree
+
+**Component-Specific ADRs**: See `ai-docs/decisions/` for component-specific decisions
+
+---
+
+**Note**: These links point to Platform (ecosystem hub) documentation. Component-specific patterns and decisions are documented in the `ai-docs/` directory of this repository.
+
+**Last Updated**: YYYY-MM-DD
diff --git a/plugins/agentic-docs/skills/component-docs/templates/exec-plans-README-template.md b/plugins/agentic-docs/skills/component-docs/templates/exec-plans-README-template.md
new file mode 100644
index 000000000..f5339654d
--- /dev/null
+++ b/plugins/agentic-docs/skills/component-docs/templates/exec-plans-README-template.md
@@ -0,0 +1,31 @@
+# Execution Plans
+
+> **Exec-Plans Guidance**: See [Platform Exec-Plans Guide](Platform documentation) for:
+> - What are exec-plans?
+> - When to create them
+> - How to use them
+> - Completion workflow
+> - Template
+
+## Component-Specific Exec-Plans
+
+Active exec-plans for this component are tracked in `active/`:
+
+```text
+exec-plans/
+└── active/              # Create feature-specific exec-plans here
+```text
+
+## Usage
+
+```bash
+# Get template from Platform
+curl -O https://raw.githubusercontent.com/openshift/enhancements/master/ai-docs/workflows/exec-plans/template.md
+
+# Create exec-plan
+mv template.md active/feature-name.md
+
+# Fill in and track during implementation
+```text
+
+See [Platform Exec-Plans Guide](Platform documentation) for complete documentation.
diff --git a/plugins/agentic-docs/skills/update-platform-docs/SKILL.md b/plugins/agentic-docs/skills/update-platform-docs/SKILL.md
new file mode 100644
index 000000000..a452b50f1
--- /dev/null
+++ b/plugins/agentic-docs/skills/update-platform-docs/SKILL.md
@@ -0,0 +1,349 @@
+---
+name: update-platform-docs
+description: Update existing platform documentation with automatic gap detection in openshift/enhancements
+trigger: explicit
+model: sonnet
+---
+
+# Platform Documentation Updater
+
+Incrementally update existing AI-optimized platform documentation in `openshift/enhancements/ai-docs/` without regenerating everything.
+
+**Features:**
+- **Automatic gap detection** - Scans ai-docs/ and reports missing files
+- **Targeted updates** - Add specific content without full regeneration
+- **Smart navigation** - Auto-updates index files and AGENTS.md
+- **Validation** - Ensures quality and conventions
+
+**Use when:**
+- Discovering what's missing from documentation
+- Adding new content to existing documentation
+- Adding new sections (e.g., workflows/exec-plans/)
+- Updating AGENTS.md with new links
+- Adding new domain concepts, patterns, or ADRs
+- Fixing or enhancing existing files
+
+**Don't use when:**
+- You want to completely regenerate all docs from scratch
+
+## Execution Workflow
+
+### Phase 1: Discovery & Gap Detection
+- [ ] Find skill directory: `SKILL_DIR=$(find ~/.claude/plugins/cache -path "*/update-platform-docs" -type d | head -1)`
+- [ ] Determine repo path: `REPO_PATH="${provided_path:-$PWD}"`
+- [ ] Run discovery: `bash "$SKILL_DIR/scripts/discover.sh" "$REPO_PATH"`
+- [ ] Verify ai-docs/ exists (ai-docs/ should already exist in openshift/enhancements)
+- [ ] Run gap detection: `bash "$SKILL_DIR/scripts/gap-detection.sh" "$REPO_PATH"`
+- [ ] Show gap detection results to user
+- [ ] Ask user: Fill detected gaps OR specify custom addition?
+
+### Phase 2: Perform Updates
+Based on user request, perform ONE OR MORE of:
+
+#### Add New Platform Pattern
+- [ ] Create new file in `platform/operator-patterns/`
+- [ ] Update `platform/operator-patterns/index.md`
+- [ ] Update `AGENTS.md` navigation if needed
+- [ ] Use `templates/operator-pattern-template.md` for structure
+
+#### Add New Domain Concept
+- [ ] Create new file in `domain/kubernetes/` or `domain/openshift/`
+- [ ] Update corresponding `domain/*/index.md`
+- [ ] Update `AGENTS.md` navigation if needed
+- [ ] Use `templates/domain-concept-template.md` for structure
+
+#### Add New Practice
+- [ ] Create new file in `practices/*/`
+- [ ] Update corresponding `practices/*/index.md`
+- [ ] Update `AGENTS.md` navigation if needed
+- [ ] Use `templates/practice-template.md` for structure
+
+#### Add New ADR
+- [ ] Create new file in `decisions/adr-NNNN-*.md`
+- [ ] Update `decisions/index.md`
+- [ ] Update `AGENTS.md` navigation if needed
+- [ ] Use `templates/adr-template.md` for structure
+
+#### Add New Workflow Section
+- [ ] Create new directory in `workflows/` (e.g., `exec-plans/`)
+- [ ] Create files in new section
+- [ ] Update `workflows/index.md`
+- [ ] Update `AGENTS.md` navigation if needed
+
+#### Update AGENTS.md
+- [ ] Read current `AGENTS.md`
+- [ ] Add new navigation links
+- [ ] Verify line count stays 100-200 lines
+- [ ] Maintain compressed table format
+
+#### Update Existing Files
+- [ ] Read current file
+- [ ] Make targeted updates (add section, update content)
+- [ ] Preserve existing structure
+- [ ] Maintain file length targets
+
+### Phase 3: Validation
+- [ ] Run validation: `bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH"`
+- [ ] Verify new files follow conventions
+- [ ] Verify AGENTS.md 100-200 lines
+- [ ] Verify internal links work
+
+### Phase 4: Report
+- [ ] List files created
+- [ ] List files updated
+- [ ] Show validation status
+- [ ] Suggest git commit command
+
+## Update Scenarios
+
+### Scenario 1: Add New Operator Pattern
+
+**User request:** "Add RBAC patterns to operator patterns"
+
+**Actions:**
+1. Create `platform/operator-patterns/rbac.md` using pattern template
+2. Add entry to `platform/operator-patterns/index.md`
+3. Add link to `AGENTS.md` under "Standard Operator Patterns"
+4. Validate
+
+### Scenario 2: Add New Workflow Section
+
+**User request:** "Add exec-plans guidance to workflows"
+
+**Actions:**
+1. Create `workflows/exec-plans/` directory
+2. Create `workflows/exec-plans/README.md` from template
+3. Create `workflows/exec-plans/template.md` from template
+4. Update `workflows/index.md` with new section
+5. Add link to `AGENTS.md` under "Workflows"
+6. Validate
+
+### Scenario 3: Update AGENTS.md
+
+**User request:** "Add link to new ADR in AGENTS.md"
+
+**Actions:**
+1. Read current `AGENTS.md`
+2. Find "Cross-Repo Architectural Decisions" section
+3. Add new ADR link in table format
+4. Verify line count ≤200
+5. Validate
+
+### Scenario 4: Add Multiple Related Files
+
+**User request:** "Add security practices section with STRIDE and secrets handling"
+
+**Actions:**
+1. Create `practices/security/threat-modeling.md`
+2. Create `practices/security/secrets.md`
+3. Update `practices/security/index.md`
+4. Add links to `AGENTS.md` under "Engineering Practices"
+5. Validate
+
+## File Naming Conventions
+
+**MUST follow these conventions:**
+
+1. **Index files**: Use `index.md` NOT `README.md` (exception: `exec-plans/README.md`)
+2. **ADR naming**: Use `adr-NNNN-` prefix (4 digits with leading zeros)
+3. **Short file names**: Match production conventions
+4. **Separate distinct concepts**: Don't combine multiple topics
+
+## Update Guidelines
+
+### Adding Content
+- Use appropriate template from `templates/`
+- Follow existing file structure and style
+- Maintain reference/terse style (tables, checklists)
+- Keep files within length targets (100-400 lines)
+
+### Updating AGENTS.md
+- Always read current content first
+- Add new links in appropriate sections
+- Use table format for consistency
+- Keep compressed (navigation, not prose)
+- Verify line count ≤200 after update
+
+### Updating Index Files
+- Add one-line description per new file
+- Maintain alphabetical or logical order
+- Use consistent format: `- [filename.md](filename.md) - Brief description`
+
+### Preserving Structure
+- Don't reorganize existing content unless explicitly requested
+- Match existing conventions and patterns
+- Maintain consistency with existing files
+
+## Validation
+
+After updates, verify:
+
+✅ New files use correct naming conventions
+✅ Index files updated with new entries
+✅ AGENTS.md updated if needed (and 100-200 lines)
+✅ Internal links work
+✅ Files follow reference style (tables, checklists)
+✅ No duplication of dev-guide/guidelines content
+
+## Gap Detection Mode
+
+**Automatic workflow:**
+
+1. **Scan** existing ai-docs/ structure
+2. **Compare** against expected files checklist
+3. **Report** what's missing (by category)
+4. **Ask** user which gaps to fill
+
+**Gap categories scanned:**
+- Platform Patterns (controller-runtime, status-conditions, webhooks, etc.)
+- Domain Concepts - Kubernetes (pod, service, crds)
+- Domain Concepts - OpenShift (clusteroperator, clusterversion)
+- Practices (testing, security, reliability, development)
+- Workflows (enhancement-process, implementing-features, exec-plans)
+- Decisions (adr-template, index)
+- References (repo-index, glossary, api-reference)
+- Core Files (DESIGN_PHILOSOPHY, KNOWLEDGE_GRAPH)
+- Navigation (AGENTS.md)
+
+**User chooses:**
+- Fill all detected gaps
+- Fill specific gaps (select from list)
+- Skip gaps, specify custom addition
+
+## Examples
+
+### Example 1: Gap Detection Workflow
+
+```bash
+/update-platform-docs
+
+# Automatic gap detection runs:
+🔍 Scanning ai-docs/ for gaps...
+
+## Platform Patterns
+Missing:
+  - platform/operator-patterns/webhooks.md
+  - platform/operator-patterns/finalizers.md
+
+## Workflows
+Missing:
+  - workflows/exec-plans/README.md
+  - workflows/exec-plans/template.md
+
+📊 Summary: 4 missing files detected
+
+# User selects:
+"Fill all gaps" OR "Fill exec-plans only" OR "Custom: add observability practices"
+
+# Actions: Creates missing files, updates indexes, validates
+```
+
+### Example 2: Add Exec-Plans Workflow
+
+```bash
+/update-platform-docs
+
+# User: "Add exec-plans guidance to workflows"
+
+# Actions:
+mkdir -p ai-docs/workflows/exec-plans
+# Create README.md from template
+# Create template.md from template
+# Update workflows/index.md
+# Update AGENTS.md
+# Update create-structure.sh
+# Validate
+```
+
+### Example 2: Add New Platform Pattern
+
+```bash
+/update-platform-docs
+
+# User: "Add webhooks pattern to operator patterns"
+
+# Actions:
+# Create platform/operator-patterns/webhooks.md from template
+# Update platform/operator-patterns/index.md
+# Update AGENTS.md (add link to webhooks)
+# Validate
+```
+
+### Example 3: Update Existing File
+
+```bash
+/update-platform-docs
+
+# User: "Add conversion webhooks section to webhooks.md"
+
+# Actions:
+# Read platform/operator-patterns/webhooks.md
+# Add new section with conversion webhook guidance
+# Validate (check line count, style)
+```
+
+## Arguments
+
+```bash
+/update-platform-docs [--path <repository-path>]
+```
+
+**Arguments:**
+- `--path <repository-path>`: Path to enhancements repository (default: current directory)
+- No args: Update documentation in current directory
+
+## Prerequisites
+
+**Before running:**
+1. ✅ ai-docs/ already exists in openshift/enhancements
+2. ✅ You're in openshift/enhancements repository
+3. ✅ You know what you want to add/update
+
+## Success Output
+
+```text
+✅ Platform Documentation Updated
+
+Repository: /path/to/enhancements
+
+Changes:
+  ✅ Created: ai-docs/workflows/exec-plans/README.md
+  ✅ Created: ai-docs/workflows/exec-plans/template.md
+  ✅ Updated: ai-docs/workflows/index.md
+  ✅ Updated: AGENTS.md (added exec-plans link)
+
+Validation:
+  ✅ File naming conventions correct
+  ✅ Index files updated
+  ✅ AGENTS.md: 192 lines (target: ≤200)
+  ✅ Internal links valid
+  ✅ Reference style maintained
+
+Next Steps:
+  1. Review changes
+  2. Run: git add ai-docs/ AGENTS.md
+  3. Run: git commit -m "Add exec-plans workflow guidance"
+```
+
+## Common Mistakes to Avoid
+
+### ❌ Mistake 1: Making AGENTS.md Too Long
+**Wrong:** Adding verbose descriptions to AGENTS.md
+**Right:** Keep compressed, table-based navigation only
+
+### ❌ Mistake 2: Not Updating Index Files
+**Wrong:** Creating new file without updating parent index.md
+**Right:** Always update corresponding index.md
+
+### ❌ Mistake 3: Inconsistent Naming
+**Wrong:** Creating `README.md` (except in exec-plans/) or `adr-1-topic.md`
+**Right:** Use `index.md` (or `exec-plans/README.md` as exception) and `adr-0001-topic.md`
+
+### ❌ Mistake 4: Duplicating Content
+**Wrong:** Copying content from dev-guide/guidelines
+**Right:** Link to authoritative source or reformat for AI agents
+
+## See Also
+
+- Platform Documentation (openshift/enhancements/ai-docs/) - Existing platform docs
+- `/component-docs` - Create component documentation
diff --git a/plugins/agentic-docs/skills/update-platform-docs/scripts/discover.sh b/plugins/agentic-docs/skills/update-platform-docs/scripts/discover.sh
new file mode 100755
index 000000000..d6ca8a450
--- /dev/null
+++ b/plugins/agentic-docs/skills/update-platform-docs/scripts/discover.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+# Discovery script - check what exists and learn conventions
+
+set -e
+
+REPO_PATH="${1:-.}"
+
+echo "🔍 Discovering existing structure in: $REPO_PATH"
+echo ""
+
+# Check if ai-docs exists
+if [ -d "$REPO_PATH/ai-docs" ]; then
+    echo "✅ ai-docs/ exists"
+
+    # Check index file naming
+    if ls "$REPO_PATH"/ai-docs/*/index.md >/dev/null 2>&1; then
+        echo "  ✅ Convention: Uses index.md (not README.md)"
+    fi
+
+    # Check ADR naming
+    ADR_SAMPLE=$(ls "$REPO_PATH/ai-docs/decisions/"adr-*.md 2>/dev/null | head -1)
+    if [ -n "$ADR_SAMPLE" ]; then
+        echo "  ✅ Convention: $(basename "$ADR_SAMPLE" | grep -oE '^adr-[0-9]+-')"
+    fi
+
+    # Count existing files
+    echo ""
+    echo "📊 Existing files:"
+    for dir in platform/operator-patterns platform/openshift-specifics practices/testing practices/security practices/reliability practices/development domain/kubernetes domain/openshift decisions workflows workflows/exec-plans references; do
+        if [ -d "$REPO_PATH/ai-docs/$dir" ]; then
+            COUNT=$(find "$REPO_PATH/ai-docs/$dir" -name "*.md" -type f | wc -l)
+            echo "  - $dir: $COUNT files"
+        fi
+    done
+else
+    echo "ℹ️  ai-docs/ does not exist - will create from scratch"
+    echo ""
+    echo "📋 Will create structure with conventions:"
+    echo "  - index.md for navigation files"
+    echo "  - adr-NNNN- for ADRs (4 digits)"
+    echo "  - Short file names (pyramid.md not testing-pyramid.md)"
+    echo "  - Target 150-300 lines per file"
+fi
+
+echo ""
+echo "✅ Discovery complete"
diff --git a/plugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.sh b/plugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.sh
new file mode 100755
index 000000000..b1033a0c4
--- /dev/null
+++ b/plugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.sh
@@ -0,0 +1,142 @@
+#!/bin/bash
+# Detect gaps in existing ai-docs/ structure
+
+set -e
+
+REPO_PATH="${1:-.}"
+AI_DOCS="$REPO_PATH/ai-docs"
+
+if [ ! -d "$AI_DOCS" ]; then
+    echo "❌ ai-docs/ does not exist. Use /platform-docs first."
+    exit 1
+fi
+
+echo "🔍 Scanning ai-docs/ for gaps..."
+echo ""
+
+# Track what's missing
+MISSING_COUNT=0
+
+# Function to check a category for missing files
+check_category() {
+    local category_name="$1"
+    local base_path="$2"
+    shift 2
+    local expected_files=("$@")
+
+    echo "## $category_name"
+
+    local missing=()
+    for file in "${expected_files[@]}"; do
+        if [ ! -f "$AI_DOCS/$base_path/$file" ]; then
+            missing+=("$file")
+            MISSING_COUNT=$((MISSING_COUNT + 1))
+        fi
+    done
+
+    if [ ${#missing[@]} -gt 0 ]; then
+        echo "Missing:"
+        for file in "${missing[@]}"; do
+            echo "  - $base_path/$file"
+        done
+    else
+        echo "✅ Complete"
+    fi
+    echo ""
+}
+
+# Platform Patterns
+check_category "Platform Patterns" "platform/operator-patterns" \
+    controller-runtime.md \
+    status-conditions.md \
+    webhooks.md \
+    finalizers.md \
+    rbac.md \
+    must-gather.md
+
+# Domain Concepts - Kubernetes
+check_category "Domain Concepts - Kubernetes" "domain/kubernetes" \
+    pod.md \
+    service.md \
+    crds.md
+
+# Domain Concepts - OpenShift
+check_category "Domain Concepts - OpenShift" "domain/openshift" \
+    clusteroperator.md \
+    clusterversion.md
+
+# Practices
+check_category "Practices" "practices" \
+    testing/pyramid.md \
+    testing/index.md \
+    security/index.md \
+    reliability/index.md \
+    development/index.md
+
+# Workflows
+check_category "Workflows" "workflows" \
+    enhancement-process.md \
+    implementing-features.md \
+    exec-plans/README.md \
+    exec-plans/template.md \
+    index.md
+
+# Decisions (ADRs)
+check_category "Decisions" "decisions" \
+    adr-template.md \
+    index.md
+
+# References
+check_category "References" "references" \
+    repo-index.md \
+    glossary.md \
+    api-reference.md \
+    index.md
+
+# Core Files (in ai-docs/ root)
+echo "## Core Files"
+CORE_MISSING=()
+for core in DESIGN_PHILOSOPHY.md KNOWLEDGE_GRAPH.md; do
+    if [ ! -f "$AI_DOCS/$core" ]; then
+        CORE_MISSING+=("$core")
+        MISSING_COUNT=$((MISSING_COUNT + 1))
+    fi
+done
+
+if [ ${#CORE_MISSING[@]} -gt 0 ]; then
+    echo "Missing:"
+    for core in "${CORE_MISSING[@]}"; do
+        echo "  - $core"
+    done
+else
+    echo "✅ Complete"
+fi
+echo ""
+
+# AGENTS.md (in repo root)
+echo "## Navigation"
+if [ ! -f "$REPO_PATH/AGENTS.md" ]; then
+    echo "Missing:"
+    echo "  - AGENTS.md (at repo root)"
+    MISSING_COUNT=$((MISSING_COUNT + 1))
+else
+    AGENTS_LINES=$(wc -l < "$REPO_PATH/AGENTS.md")
+    if [ "$AGENTS_LINES" -gt 200 ]; then
+        echo "⚠️  AGENTS.md exists but is too long: $AGENTS_LINES lines (target: ≤200)"
+    else
+        echo "✅ AGENTS.md exists ($AGENTS_LINES lines)"
+    fi
+fi
+echo ""
+
+# Summary
+echo "========================================"
+if [ $MISSING_COUNT -eq 0 ]; then
+    echo "✅ No gaps detected. Documentation is complete!"
+else
+    echo "📊 Summary: $MISSING_COUNT missing files detected"
+    echo ""
+    echo "Run /update-platform-docs to add missing content."
+fi
+
+exit 0
diff --git a/plugins/agentic-docs/skills/update-platform-docs/scripts/validate.sh b/plugins/agentic-docs/skills/update-platform-docs/scripts/validate.sh
new file mode 100755
index 000000000..5462433a0
--- /dev/null
+++ b/plugins/agentic-docs/skills/update-platform-docs/scripts/validate.sh
@@ -0,0 +1,152 @@
+#!/bin/bash
+# Comprehensive validation script
+
+set -e
+
+REPO_PATH="${1:-.}"
+
+echo "✅ Validating ai-docs/ in: $REPO_PATH"
+echo ""
+
+ERRORS=0
+
+# Phase 1: Entry Points (Required)
+echo "=== Phase 1: Entry Points (Required) ==="
+echo ""
+
+# AGENTS.md in repo root
+if [ ! -f "$REPO_PATH/AGENTS.md" ]; then
+    echo "  ❌ Missing: AGENTS.md (must be in repo root)"
+    ERRORS=$((ERRORS + 1))
+else
+    echo "  ✅ AGENTS.md"
+    LINE_COUNT=$(wc -l < "$REPO_PATH/AGENTS.md")
+    echo "     $LINE_COUNT lines"
+    if [ "$LINE_COUNT" -lt 100 ] || [ "$LINE_COUNT" -gt 200 ]; then
+        echo "     ⚠️  WARNING: Should be 100-200 lines (current: $LINE_COUNT)"
+    fi
+fi
+
+# ai-docs/ core files
+for file in DESIGN_PHILOSOPHY.md KNOWLEDGE_GRAPH.md; do
+    if [ ! -f "$REPO_PATH/ai-docs/$file" ]; then
+        echo "  ❌ Missing: ai-docs/$file"
+        ERRORS=$((ERRORS + 1))
+    else
+        echo "  ✅ ai-docs/$file"
+    fi
+done
+
+# Phase 2: Required Workflow Files (Explicit Checkboxes)
+echo ""
+echo "=== Phase 2: Required Workflow Files ==="
+echo ""
+
+# These two files have explicit checkboxes in the workflow - must exist
+for file in "workflows/enhancement-process.md" "workflows/implementing-features.md"; do
+    if [ ! -f "$REPO_PATH/ai-docs/$file" ]; then
+        echo "  ❌ Missing required: ai-docs/$file (explicit checkbox in workflow)"
+        ERRORS=$((ERRORS + 1))
+    else
+        echo "  ✅ ai-docs/$file"
+    fi
+done
+
+# Phase 3: Design Philosophy Coverage (Non-Prescriptive)
+echo ""
+echo "=== Phase 3: Design Philosophy Coverage ==="
+echo ""
+
+echo "Checking for pattern documentation:"
+PATTERN_COUNT=$(find "$REPO_PATH/ai-docs/platform" -name "*.md" -type f 2>/dev/null | wc -l)
+if [ "$PATTERN_COUNT" -gt 0 ]; then
+    echo "  ✅ Found $PATTERN_COUNT platform pattern files"
+else
+    echo "  ⚠️  No platform pattern files found (consider documenting key operator patterns)"
+fi
+
+echo ""
+echo "Checking for domain documentation:"
+DOMAIN_COUNT=$(find "$REPO_PATH/ai-docs/domain" -name "*.md" -type f 2>/dev/null | wc -l)
+if [ "$DOMAIN_COUNT" -gt 0 ]; then
+    echo "  ✅ Found $DOMAIN_COUNT domain concept files"
+else
+    echo "  ⚠️  No domain concept files found (consider documenting core APIs)"
+fi
+
+echo ""
+echo "Checking for practices documentation:"
+PRACTICE_COUNT=$(find "$REPO_PATH/ai-docs/practices" -name "*.md" -type f 2>/dev/null | wc -l)
+if [ "$PRACTICE_COUNT" -gt 0 ]; then
+    echo "  ✅ Found $PRACTICE_COUNT practice files"
+else
+    echo "  ⚠️  No practice files found (ensure cross-cutting concerns are covered)"
+fi
+
+# Phase 4: Avoid Duplication
+echo ""
+echo "=== Phase 4: Duplication Check ==="
+echo ""
+
+echo "Checking for pointer-based references:"
+if [ -f "$REPO_PATH/ai-docs/references/repo-index.md" ]; then
+    if grep -q "github.com/orgs/openshift" "$REPO_PATH/ai-docs/references/repo-index.md" 2>/dev/null; then
+        echo "  ✅ repo-index.md uses GitHub org links (good)"
+    else
+        echo "  ⚠️  repo-index.md should use GitHub org search links, not exhaustive lists"
+    fi
+fi
+
+if [ -f "$REPO_PATH/ai-docs/references/api-reference.md" ]; then
+    if grep -q "oc api-resources" "$REPO_PATH/ai-docs/references/api-reference.md" 2>/dev/null; then
+        echo "  ✅ api-reference.md points to oc command (good)"
+    else
+        echo "  ⚠️  api-reference.md should reference 'oc api-resources', not list all APIs"
+    fi
+fi
+
+# Phase 5: Structural Quality
+echo ""
+echo "=== Phase 5: Structural Quality ==="
+echo ""
+
+# Check for index files in directories with content
+echo "Checking for index files in populated directories:"
+for dir in platform practices domain decisions workflows references; do
+    if [ -d "$REPO_PATH/ai-docs/$dir" ]; then
+        FILE_COUNT=$(find "$REPO_PATH/ai-docs/$dir" -maxdepth 2 -name "*.md" -type f 2>/dev/null | wc -l)
+        if [ "$FILE_COUNT" -gt 1 ]; then
+            # Directory has content, should have navigation
+            INDEX_COUNT=$(find "$REPO_PATH/ai-docs/$dir" -maxdepth 2 -name "index.md" -type f 2>/dev/null | wc -l)
+            if [ "$INDEX_COUNT" -gt 0 ]; then
+                echo "  ✅ $dir/ has index files for navigation"
+            else
+                echo "  ⚠️  $dir/ has $FILE_COUNT files but no index.md for navigation"
+            fi
+        fi
+    fi
+done
+
+# Check ADR naming format (if ADRs exist)
+echo ""
+echo "Checking ADR naming format:"
+ADR_COUNT=$(find "$REPO_PATH/ai-docs/decisions" -name "adr-*.md" -type f 2>/dev/null | wc -l)
+if [ "$ADR_COUNT" -gt 0 ]; then
+    INVALID_ADRS=$(find "$REPO_PATH/ai-docs/decisions" -name "adr-*.md" -type f 2>/dev/null | grep -v -E 'adr-[0-9]{4}-' | wc -l)
+    if [ "$INVALID_ADRS" -eq 0 ]; then
+        echo "  ✅ All ADRs use adr-NNNN- format"
+    else
+        echo "  ⚠️  Some ADRs don't use adr-NNNN- format"
+    fi
+fi
+
+# Summary
+echo ""
+echo "==================================="
+if [ "$ERRORS" -eq 0 ]; then
+    echo "✅ Validation PASSED - All checks successful"
+    exit 0
+else
+    echo "❌ Validation FAILED - Found $ERRORS errors"
+    exit 1
+fi
diff --git a/plugins/agentic-docs/skills/update-platform-docs/templates/adr-template.md b/plugins/agentic-docs/skills/update-platform-docs/templates/adr-template.md
new file mode 100644
index 000000000..3583214f3
--- /dev/null
+++ b/plugins/agentic-docs/skills/update-platform-docs/templates/adr-template.md
@@ -0,0 +1,67 @@
+---
+title: Decision Title
+status: Accepted | Proposed | Deprecated | Superseded
+date: YYYY-MM-DD
+affected_components:
+  - component-1
+  - component-2
+---
+
+# ADR NNNN: Decision Title
+
+## Status
+
+**Accepted** | **Proposed** | **Deprecated** | **Superseded by ADR-XXXX**
+
+## Context
+
+What is the background or problem that requires a decision?
+
+## Decision
+
+What is the decision that was made?
+
+## Rationale
+
+Why was this decision made?
+
+- ✅ **Pro 1**: Benefit
+- ✅ **Pro 2**: Benefit
+- ✅ **Pro 3**: Benefit
+
+## Alternatives Considered
+
+### Alternative 1
+- **Pro**: Advantages
+- **Con**: Disadvantages
+- **Why not chosen**: Reason
+
+### Alternative 2
+- **Pro**: Advantages
+- **Con**: Disadvantages
+- **Why not chosen**: Reason
+
+## Consequences
+
+**Positive**:
+- Benefit 1
+- Benefit 2
+
+**Negative**:
+- Trade-off 1
+- Trade-off 2
+
+## Affected Components
+
+- **component-1**: How it's affected
+- **component-2**: How it's affected
+
+## Mitigation
+
+- **Issue 1**: How it's mitigated
+- **Issue 2**: How it's mitigated
+
+## References
+
+- **Upstream**: https://reference
+- **Related**: [related-doc.md](./related.md)
diff --git a/plugins/agentic-docs/skills/update-platform-docs/templates/domain-concept-template.md b/plugins/agentic-docs/skills/update-platform-docs/templates/domain-concept-template.md
new file mode 100644
index 000000000..4e35333ee
--- /dev/null
+++ b/plugins/agentic-docs/skills/update-platform-docs/templates/domain-concept-template.md
@@ -0,0 +1,74 @@
+# Concept Name
+
+**Type**: Kubernetes Core Concept / OpenShift Platform Concept  
+**API Group**: `apigroup.k8s.io/v1` or `config.openshift.io/v1`  
+**Last Updated**: YYYY-MM-DD  
+
+## Overview
+
+What this resource is and its purpose.
+
+## Key Concepts
+
+- **Concept 1**: Definition
+- **Concept 2**: Definition
+- **Lifecycle**: Brief description
+
+## API Structure
+
+```yaml
+apiVersion: group/version
+kind: ResourceKind
+metadata:
+  name: example
+spec:
+  field1: value
+  field2: value
+status:
+  condition: value
+```text
+
+## Common Patterns
+
+### Pattern 1
+```yaml
+# Example YAML
+```text
+**Use case**: When to use this pattern
+
+### Pattern 2
+```yaml
+# Another example
+```text
+**Use case**: When to use this pattern
+
+## Lifecycle / Workflow
+
+```text
+Step 1 → Step 2 → Step 3 → Step 4
+```text
+
+Brief explanation of the flow.
+
+## Examples
+
+### Example 1: Common Use Case
+```yaml
+# Practical example
+```text
+
+### Example 2: Advanced Use Case
+```yaml
+# Advanced example
+```text
+
+## Related Concepts
+
+- **Related 1**: [file.md](./file.md)
+- **Related 2**: [file.md](./file.md)
+
+## References
+
+- **Upstream**: https://kubernetes.io/docs/...
+- **OpenShift**: [pattern.md](../../platform/...)
+- **API**: https://github.com/openshift/api/...
diff --git a/plugins/agentic-docs/skills/update-platform-docs/templates/operator-pattern-template.md b/plugins/agentic-docs/skills/update-platform-docs/templates/operator-pattern-template.md
new file mode 100644
index 000000000..10eb85476
--- /dev/null
+++ b/plugins/agentic-docs/skills/update-platform-docs/templates/operator-pattern-template.md
@@ -0,0 +1,57 @@
+# Pattern Name
+
+**Category**: Platform Pattern  
+**Applies To**: All ClusterOperators / Specific operator types  
+**Last Updated**: YYYY-MM-DD  
+
+## Overview
+
+Brief description of what this pattern is and why it exists.
+
+## Key Concepts
+
+- **Concept 1**: Definition
+- **Concept 2**: Definition
+- **Concept 3**: Definition
+
+## Implementation
+
+```go
+// Code example showing the pattern
+import "relevant/package"
+
+func ExampleImplementation() {
+    // Show actual code
+}
+```text
+
+## Best Practices
+
+1. **Practice 1**: Explanation
+2. **Practice 2**: Explanation
+3. **Practice 3**: Explanation
+
+## Common Patterns
+
+### Pattern Variant 1
+```yaml
+# YAML or code example
+```text
+
+### Pattern Variant 2
+```go
+// Another code example
+```text
+
+## Examples in Components
+
+| Component | Implementation | Notes |
+|-----------|---------------|-------|
+| component-1 | path/to/file.go | What it does |
+| component-2 | path/to/file.go | What it does |
+
+## References
+
+- **Upstream**: https://link-to-upstream-docs
+- **OpenShift**: [related-pattern.md](./related-pattern.md)
+- **API**: https://github.com/openshift/api/...
diff --git a/plugins/agentic-docs/skills/update-platform-docs/templates/practice-template.md b/plugins/agentic-docs/skills/update-platform-docs/templates/practice-template.md
new file mode 100644
index 000000000..9354ce215
--- /dev/null
+++ b/plugins/agentic-docs/skills/update-platform-docs/templates/practice-template.md
@@ -0,0 +1,52 @@
+# Practice Name
+
+**Category**: Engineering Practice  
+**Applies To**: All OpenShift repositories / Specific areas  
+**Last Updated**: YYYY-MM-DD  
+
+## Overview
+
+What this practice is and why it matters.
+
+## Philosophy
+
+Core principle or diagram explaining the approach.
+
+## Implementation
+
+### Step 1: First Action
+```bash
+# Commands or code
+```text
+
+**What to do**: Explanation
+**When to use**: Guidance
+
+### Step 2: Second Action
+```bash
+# More commands
+```text
+
+## Best Practices
+
+1. **Practice 1**: Explanation with rationale
+2. **Practice 2**: Explanation with rationale
+3. **Practice 3**: Explanation with rationale
+
+## Anti-Patterns
+
+**Wrong approach**: Description
+**Why it's bad**: Explanation
+**Right approach**: Correct way
+
+## Examples in Components
+
+| Component | Implementation | Notes |
+|-----------|---------------|-------|
+| component-1 | Location | What they do |
+| component-2 | Location | What they do |
+
+## References
+
+- **Guide**: [related-doc.md](./related-doc.md)
+- **Upstream**: https://external-reference