Component Docs

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 the openshift/enhancements repo (dev-guide/, guidelines/, CONVENTIONS.md). Code is the source of truth — read it, verify claims against it, but link to existing repo docs that explain the "why".

Two-Tier Architecture

Platform: openshift/enhancements

Contains: Development conventions (dev-guide/), coding standards (CONVENTIONS.md), enhancement guidelines (guidelines/), cross-repo architectural context

Component: Component Repos (LEAN)

Contains: Component-specific architecture, behavioral contracts, development guides, test patterns

Decision Rule: "Would another repo need to duplicate this?"

• YES → Platform (platform)
• NO → Component (component)

What Gets Created

component-repo/
├── AGENTS.md                      # Executive briefing (40-60 lines)
├── CLAUDE.md → AGENTS.md          # Symlink (Claude Code auto-loads)
├── REVIEW.md                      # Review instructions (Claude Code Review + CodeRabbit)
├── .coderabbit.yaml               # CodeRabbit config (points at REVIEW.md)
└── ai-docs/
    ├── ARCHITECTURE.md            # Internals, integrations, behavioral contracts, design refs
    ├── DEVELOPMENT.md             # Build, common tasks, mistakes
    ├── TESTING.md                 # Test suites and patterns
    └── ENHANCEMENTS.md            # Optional — enhancement/KEP/design doc catalog

What NOT to Include (lives in Platform)

❌ Generic framework patterns (controller-runtime, status conditions, common libraries) ❌ 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)

Hosted knowledge resources

If running inside the Chai Bot environment, use the documentation and other resources configured there, including Slack, Jira, and CodeRAG knowledge. Verify cross-repository facts against authoritative sources, such as upstream GitHub sources or Chai Bot's configured CodeRAG. See Phase 1 for specific query steps.

Execution Workflow

Phase 1: Setup

• Read existing CLAUDE.md / AGENTS.md before overwriting: If the repo already has either file, read it first and extract important points (build instructions, critical warnings, repo conventions, key patterns, retrieval priorities, documentation maps, and useful direct links) to incorporate into the generated docs. Existing content is prior work — preserve it, don't overwrite blindly.
• Back up prior agent docs before writing: Save any existing CLAUDE.md / AGENTS.md content under ai-docs/_sources/. Use them as temporary source material for review and recovery during generation.
• Discover existing repo docs: Scan docs/, docs/enhancements/, design/, CONTRIBUTING.md, and any files with "design", "proposal", "enhancement" in the name. These will be linked from ENHANCEMENTS.md and ARCHITECTURE.md as appropriate. Also scan documentation files at the repository root and look elsewhere throughout the repository for relevant documentation, regardless of filename or location.
• Record documentation sources used: As existing repository documents are used as sources, record each repo-relative path in ai-docs/_sources/repository-docs-used.txt, one path per line.
• Resolve this skill directory from the location of the loaded SKILL.md. Resolve all scripts/, templates/, and guides/ paths relative to it. Do not search a plugin cache or assume the repository is the current directory.
• Preflight required resources: scripts/create-structure.sh, scripts/validate.sh, scripts/cleanup-sources.sh, all referenced templates, and any guide required by the selected execution path. Stop before writing if a required resource is unavailable.
• Determine repo path: REPO_PATH="${provided_path:-$PWD}"
• Detect component name from repo (e.g., machine-config-operator → MCO)
• Run the resolved scripts/create-structure.sh with "$REPO_PATH".
• Gather tribal knowledge (Chai Bot / hosted environment): If knowledge tools (researcher, Slack, Jira) are available, query them for tribal knowledge about this repository:
  • Search for "<repo-name> convention OR pitfall OR mistake OR gotcha"
  • Search for "<repo-name> review process OR reviewer expectations"
  • Search for "<repo-name> common rejection OR frequently rejected"
  • Search for "<repo-name> design decision OR historical context"
  • Save findings to ai-docs/_sources/tribal-knowledge-notes.md for use in later phases
  • If no hosted knowledge tools are available, skip this step

Phase 2: Create AGENTS.md (40-60 lines)

• Create initial AGENTS.md at repo root using templates/AGENTS-template.md
• If existing AGENTS.md/CLAUDE.md was found in Phase 1, incorporate its critical warnings and conventions
• Treat AGENTS.md as the executive summary only. If the old CLAUDE.md contains longer repo-specific operational detail (release/bundle commands, CI/Konflux notes, metrics/debugging guidance), move that detail into DEVELOPMENT.md or ARCHITECTURE.md instead of dropping it.
• Preserve valuable navigation from prior agent docs. Keep compact, frequently used direct links in AGENTS.md. A detailed "need → start here" map may move to ARCHITECTURE.md or ENHANCEMENTS.md, but AGENTS.md must link directly to that map. Do not replace useful deep links with only a bare directory name.
• Include architecture-at-a-glance summary
• Revisit after Phase 4: Fill in the Critical Warnings section with 3-5 "never do X" rules discovered during architecture exploration
• Create CLAUDE.md symlink: ln -sf AGENTS.md "$REPO_PATH/CLAUDE.md"
• Validate line count: wc -l AGENTS.md (target: 40-60)

Phase 3: ENHANCEMENTS.md (Optional)

• Search component repo for local design docs:
  • Check docs/, design/, enhancements/ directories
  • Check for files with "design", "proposal", "enhancement" in name
• Search openshift/enhancements repo for component-specific proposals:
  • Check https://github.com/openshift/enhancements/tree/master/enhancements/{component-area}/
• Search for related upstream KEPs (Kubernetes Enhancement Proposals)
• Only create ai-docs/ENHANCEMENTS.md if content exists — do not create an empty file
• Format: title, status (implemented/provisional/rejected), link only — keep concise
• Link to all found docs — these are authoritative sources, the enhancement is the source of truth
• Note: Enhancement proposals are feature designs (often cross-component). Key architectural decisions go inline in ARCHITECTURE.md "Design References" section, not here.

Phase 4: Component Architecture (ARCHITECTURE.md)

• Read one complete implementation first: Pick one controller/component package (preferably the most recently added). Read ALL files in it — not just controller.go, but constants, utils, every reconciler file, install sequence, and tests. This is your reference implementation. Document every pattern you observe: how it applies resources, what shared utilities it calls, what predicates it uses, what constants it defines, what env vars it reads. If the repo has 2+ similar components, compare them — divergences in approach are the most valuable thing to document ("use X pattern from component A, not Y pattern from component B").
• Detect repo type: Check for operator signals (controller-runtime, library-go, operator-sdk, OLM bundle in bundle/, CRDs in config/crd/). If operator detected, follow the Operator-Specific Discovery checklist below in addition to the generic checklist.
• Explore remaining codebase: Read entrypoints, key packages, dependencies. Follow the Implementation Pattern Discovery checklist below.
• Create ai-docs/ARCHITECTURE.md with the following required sections:

ARCHITECTURE.md Required Sections (target: 200-400 lines):

1. Repository Layout — annotated directory tree with actionable annotations ("DO NOT use X for Y")
2. Key Domain Concepts — the core abstractions an agent must understand before touching this codebase. Not struct fields (agents read types.go), but the mental model: what are the primary resources, how do they relate, what are the key lifecycle flows. For operators: trace the primary end-to-end workflow (e.g., "user creates CR → controller renders config → daemon applies to node → node reboots"). For libraries: what are the key interfaces and their contracts. This section answers "what does this system DO" before the next sections explain "how is it BUILT"
3. Component/Controller Details — framework, startup sequence, per-controller tables
4. Resource Management — apply methods per controller (SSA, strategic merge, Create/Update), image resolution, deployment hooks
5. Feature Gates — definition → runtime check → startup wiring chain
6. Error Classification — error types, requeue behavior, status condition effects
7. OpenShift Integration Points — upstream project dependencies, OpenShift component integrations (CNO, CCO, OLM, proxy, TLS, etc.) with integration tables
8. Generated Code Inventory — generated files/dirs with "NEVER hand-edit" + make target
9. API Behavioral Contracts — behavioral knowledge that agents can't get from reading types.go alone: singleton constraints, naming conventions, merging order, lifecycle flows, config drift detection, plugin behaviors, gotchas, "DO NOT" rules. Point agents to types.go / api/ for actual struct field definitions
10. Form Factor Behavior (if applicable) — how the component behaves across deployment topologies: Standalone, SNO (replica adjustments, resource constraints), HCP/Hosted Control Planes (which cluster does it run in, cross-cluster communication), MicroShift (does it run, config alternatives). Only document form factors the code actually handles. Table format preferred
11. Design References — 2-3 key architectural decisions inline (5-8 lines each: title, decision, rationale, consequences). Link to existing repo design docs (from docs/) where they provide deeper detail
12. Platform Documentation — link to the openshift/enhancements repo for generic platform patterns. Reference stable paths: dev-guide/ for development conventions, guidelines/ for enhancement process, CONVENTIONS.md for coding standards. Do NOT link to specific files under ai-docs/ — that structure is subject to change

• Document discovered patterns using the discovery checklist results
• Link to existing repo docs (from docs/, design docs) where they provide deeper detail — ARCHITECTURE.md is a map, not a replacement for existing documentation
• Keep lean but dense (every line should tell the reader something they can't infer from file names alone)
• Every pattern claim must include a file:line reference. If you can't point to source, flag as unverified
• Integrate tribal knowledge: If ai-docs/_sources/tribal-knowledge-notes.md exists from Phase 1, incorporate relevant findings:
  • Historical design decisions → "Design References" section
  • Cross-repo interaction patterns → "OpenShift Integration Points" section
  • Attribute integrated knowledge where it adds credibility (e.g. "Historically, the team has...")

Phase 5: Development & Testing Docs

• VERIFY FIRST:

  # Go version
  grep "^go " "$REPO_PATH/go.mod"
  
  # Branch name (no clone needed) — uses first remote found
  _remote=$(git remote | head -1)
  git ls-remote --symref "$(git remote get-url "$_remote")" HEAD | grep 'ref:' | awk '{print $2}' | cut -d/ -f3
  
  # Makefile targets
  grep "^[a-zA-Z-]*:" Makefile | cut -d: -f1
  
  # Directory structure
  ls -d cmd pkg test manifests 2>/dev/null

• Create ai-docs/DEVELOPMENT.md using templates/DEVELOPMENT-template.md:
  • Do not repeat repo layout — it is in ARCHITECTURE.md
  • Replace generic template placeholders with actual repo patterns discovered in Phase 4
  • Fill "Common Tasks" with repo-specific tasks, not generic placeholders
  • Fill "Common Mistakes" from anti-patterns discovered in Phase 4
  • Preserve still-relevant operational detail from the prior CLAUDE.md (for example: bundle/catalog/release commands, CI/Konflux notes, metrics/debugging commands, non-default environment variables)
  • If common tasks vary in complexity, document tiers with specific file modification lists
• Create ai-docs/TESTING.md using templates/TESTING-template.md:
  • Replace generic code examples with actual test patterns from this repo
  • Fill "Component-Specific" sections with real test scenarios
• Link to Platform for generic practices
• Document ONLY verified component-specific details (target: 100-200 lines each)
• Integrate tribal knowledge: If tribal knowledge notes exist, incorporate:
  • Undocumented conventions → DEVELOPMENT.md
  • Common pitfalls → "Common Mistakes" section
  • Review process norms → DEVELOPMENT.md or REVIEW.md as appropriate

Phase 6: Generate REVIEW.md + .coderabbit.yaml (REQUIRED)

• Read and follow guides/REVIEW-GENERATION.md — all 8 steps are required
• Do not skip — REVIEW.md and .coderabbit.yaml are mandatory outputs

Phase 7: Validation & Verification

• Run the resolved scripts/validate.sh with "$REPO_PATH" (includes link validation and removal of broken external-link lines)
• Verify ai-docs/_sources/ contains backups of any prior CLAUDE.md / AGENTS.md that existed
• Verify AGENTS.md 40-60 lines, no generic duplication
• Verify CLAUDE.md → AGENTS.md symlink exists
• Verify ARCHITECTURE.md 200-400 lines, contains required sections (repo layout, API Behavioral Contracts, Design References, Platform Documentation)
• Verify specificity: Pattern claims backed by code evidence, not generic placeholders
• Anti-hallucination checks: Spot-check type fields if applicable, verify branch names in examples match repo, confirm pattern claims reference actual code
• Operator-specific checks (if operator repo): Verify apply method claims per-controller (grep -r "client.Apply\|r.Update\|resourceapply" pkg/controller/<name>/). Verify feature gate claims trace to actual runtime code. Verify image env var names match Makefile/CSV.
• REVIEW.md checks: exists at repo root, ≤100 lines (wc -l REVIEW.md), skip paths reference real directories (test -d), platform citations present (grep for "dev-guide" or "CONVENTIONS"), no content overlap with AGENTS.md
• .coderabbit.yaml checks: valid YAML (python3 -c "import yaml; yaml.safe_load(open('.coderabbit.yaml'))"), filePatterns contains "REVIEW.md" but NOT "CLAUDE.md", path_filters match "Do not report" globs, path_instructions match "Path-specific rules"
• Cross-check with openshift-docs if time permits
• Verify tribal knowledge integration: If tribal knowledge was gathered in Phase 1, confirm that relevant findings were integrated into the documentation. If relevant findings were discovered but none were integrated, flag this as incomplete and explain why each finding was excluded.
• Flag discovery gaps: At the end of ARCHITECTURE.md and DEVELOPMENT.md, add a brief "SME Review Recommended" note listing areas where automated discovery may be incomplete
• No silent drops: Compare the prior CLAUDE.md / AGENTS.md against the generated docs and ensure repo-specific commands, CI notes, metrics/debug tips, hard warnings, retrieval instructions, documentation maps, and useful direct links were preserved. For every relocated item, verify the new location and leave a discoverable route from AGENTS.md. Record any intentional drop and its rationale in the completion report.
• Source-document links: For every path recorded in _sources/repository-docs-used.txt, verify the document is linked from AGENTS.md or ai-docs/. Record any intentional exception and its rationale in the completion report.
• Cleanup: After validation passes, run the resolved scripts/cleanup-sources.sh with "$REPO_PATH". Do not leave temporary source backups in the final repo tree.

Link Validation:

• Link validation always runs — broken links (wrong relative paths, 404 URLs) are a common source of documentation errors
• Automatically checks all HTTP/HTTPS links (with timeout and user agent)
• Validates internal/relative links (file existence)
• Use VERBOSE=true with the resolved validator to see successful links. Use CHECK_EXTERNAL_LINKS=false when the host intentionally has no network access; report external links as unverified in that mode.