From 1b5afd1273f565bf2a217781f02a9f217f81a5ec Mon Sep 17 00:00:00 2001 From: Prashanth684 Date: Wed, 29 Apr 2026 10:59:26 -0700 Subject: [PATCH 1/3] Add agentic-docs plugin: tier-1 platform documentation Introduces tier-1 platform documentation skills for creating and maintaining AI-optimized documentation in openshift/enhancements. Skills: /agentic-docs:platform (/platform-docs): Creates tier-1 platform documentation with: - AGENTS.md navigation index - DESIGN_PHILOSOPHY.md and KNOWLEDGE_GRAPH.md - platform/, domain/, practices/, decisions/, workflows/, references/ - Automated discovery, structure creation, template population, and validation /agentic-docs:update-platform-docs (/update-platform-docs): Incrementally updates tier-1 documentation with: - Automatic gap detection (scans existing ai-docs/ for missing files) - Targeted additions without full regeneration - Smart navigation updates (auto-updates indexes and AGENTS.md) - Validation of naming conventions, line counts, and link integrity --- .claude-plugin/marketplace.json | 6 + docs/data.json | 17 +- .../agentic-docs/.claude-plugin/plugin.json | 8 + plugins/agentic-docs/README.md | 49 ++ plugins/agentic-docs/skills/platform/SKILL.md | 626 ++++++++++++++++++ .../platform/scripts/create-structure.sh | 32 + .../skills/platform/scripts/discover.sh | 46 ++ .../skills/platform/scripts/fill-gaps.sh | 96 +++ .../skills/platform/scripts/gap-detection.sh | 142 ++++ .../platform/scripts/populate-templates.sh | 28 + .../skills/platform/scripts/validate.sh | 152 +++++ .../skills/platform/templates/AGENTS.md | 63 ++ .../platform/templates/DESIGN_PHILOSOPHY.md | 121 ++++ .../platform/templates/KNOWLEDGE_GRAPH.md | 136 ++++ .../skills/platform/templates/adr-template.md | 67 ++ .../templates/domain-concept-template.md | 74 +++ .../templates/operator-pattern-template.md | 57 ++ .../platform/templates/practice-template.md | 52 ++ .../templates/workflows/exec-plan-template.md | 74 +++ .../templates/workflows/exec-plans-README.md | 188 ++++++ .../skills/update-platform-docs/SKILL.md | 365 ++++++++++ .../update-platform-docs/scripts/discover.sh | 1 + .../scripts/gap-detection.sh | 1 + .../update-platform-docs/scripts/validate.sh | 1 + .../skills/update-platform-docs/templates | 1 + 25 files changed, 2402 insertions(+), 1 deletion(-) create mode 100644 plugins/agentic-docs/.claude-plugin/plugin.json create mode 100644 plugins/agentic-docs/README.md create mode 100644 plugins/agentic-docs/skills/platform/SKILL.md create mode 100755 plugins/agentic-docs/skills/platform/scripts/create-structure.sh create mode 100755 plugins/agentic-docs/skills/platform/scripts/discover.sh create mode 100755 plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh create mode 100755 plugins/agentic-docs/skills/platform/scripts/gap-detection.sh create mode 100755 plugins/agentic-docs/skills/platform/scripts/populate-templates.sh create mode 100755 plugins/agentic-docs/skills/platform/scripts/validate.sh create mode 100644 plugins/agentic-docs/skills/platform/templates/AGENTS.md create mode 100644 plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md create mode 100644 plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md create mode 100644 plugins/agentic-docs/skills/platform/templates/adr-template.md create mode 100644 plugins/agentic-docs/skills/platform/templates/domain-concept-template.md create mode 100644 plugins/agentic-docs/skills/platform/templates/operator-pattern-template.md create mode 100644 plugins/agentic-docs/skills/platform/templates/practice-template.md create mode 100644 plugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.md create mode 100644 plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md create mode 100644 plugins/agentic-docs/skills/update-platform-docs/SKILL.md create mode 120000 plugins/agentic-docs/skills/update-platform-docs/scripts/discover.sh create mode 120000 plugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.sh create mode 120000 plugins/agentic-docs/skills/update-platform-docs/scripts/validate.sh create mode 120000 plugins/agentic-docs/skills/update-platform-docs/templates 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..9d6c67ef3 100644 --- a/docs/data.json +++ b/docs/data.json @@ -1822,6 +1822,21 @@ "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 AI-optimized platform documentation for openshift/enhancements", + "id": "platform", + "name": "platform" + } + ], + "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/README.md b/plugins/agentic-docs/README.md new file mode 100644 index 000000000..699af9c75 --- /dev/null +++ b/plugins/agentic-docs/README.md @@ -0,0 +1,49 @@ +# Agentic Docs + +AI-optimized OpenShift documentation with progressive disclosure, reference style (tables/checklists), and pointer-based navigation. + +## Two-Tier Architecture + +**Tier 1: Platform Hub** (`openshift/enhancements/ai-docs/`) +Generic patterns, testing, security, K8s/OpenShift fundamentals, cross-repo ADRs. ~34 files, 4.4k lines. + +**Tier 2: Component Repos** (`{component}/agentic/`) +Component CRDs, architecture, local ADRs, exec-plans. Links to Tier 1. ~15 files, 2.5k lines (58% leaner). + +## Skills + +### `/platform-docs` +Creates Tier 1 platform documentation in `openshift/enhancements/ai-docs/`. + +```bash +cd /path/to/openshift/enhancements +/platform-docs +``` + +Creates AGENTS.md (navigation) + ai-docs/ with: platform patterns (controller-runtime, webhooks, finalizers, RBAC, must-gather), domain concepts (K8s/OpenShift APIs), practices (testing, security, reliability), cross-repo ADRs, workflows (exec-plans, enhancement process), and references (repo-index, glossary, API pointers). + +### `/update-docs` +Incrementally update Tier 1 docs with automatic gap detection. + +```bash +cd /path/to/openshift/enhancements +/update-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 when ai-docs/ exists (otherwise use `/platform-docs`). + +### `/component-docs` +Creates Tier 2 lean docs in component repositories. + +```bash +cd /path/to/component-repository +/component-docs +``` + +Creates AGENTS.md + agentic/ with: component CRDs only, architecture, component ADRs, exec-plans, ecosystem links to Tier 1, development/testing guides. Excludes generic patterns (lives in Tier 1). Example: [machine-config-operator/agentic](https://github.com/openshift/machine-config-operator/tree/master/agentic). + +## Development + +Skills live under `skills/{platform,update-platform-docs,component}/` with SKILL.md, scripts, and templates. + +**License:** Apache 2.0 diff --git a/plugins/agentic-docs/skills/platform/SKILL.md b/plugins/agentic-docs/skills/platform/SKILL.md new file mode 100644 index 000000000..12c87ca21 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/SKILL.md @@ -0,0 +1,626 @@ +--- +name: platform-docs +description: Create AI-optimized platform documentation for openshift/enhancements +trigger: explicit +model: sonnet +--- + +# Platform Documentation Creator + +Creates AI-optimized platform documentation in `openshift/enhancements` repository under `ai-docs/`. + +## 🚨 EXECUTION WORKFLOW 🚨 + +**Follow this workflow. Create documentation based on principles, not arbitrary counts.** + +### Phase 1: Setup βš™οΈ +- [ ] Find skill directory: `SKILL_DIR=$(find ~/.claude/plugins/cache -path "*/platform" -type d | head -1)` +- [ ] Determine repo path: `REPO_PATH="${provided_path:-$PWD}"` +- [ ] Run discovery: `bash "$SKILL_DIR/scripts/discover.sh" "$REPO_PATH"` +- [ ] IF `ai-docs/` doesn't exist: Run `bash "$SKILL_DIR/scripts/create-structure.sh" "$REPO_PATH"` +- [ ] IF `ai-docs/` doesn't exist: Run `bash "$SKILL_DIR/scripts/populate-templates.sh" "$REPO_PATH"` +- [ ] IF `ai-docs/` exists: Run `bash "$SKILL_DIR/scripts/fill-gaps.sh" "$REPO_PATH"` + +### Phase 2: Master Entry Point πŸ“„ +- [ ] Create `AGENTS.md` in repo root (~100-200 lines, use templates/AGENTS.md as reference) +- [ ] Validate line count: `wc -l AGENTS.md` (target: 100-200 lines) + +### Phase 3: Platform Patterns πŸ”§ +- [ ] Read DESIGN_PHILOSOPHY.md to understand core principles +- [ ] For each principle, identify patterns needed to implement it +- [ ] Create pattern docs ONLY if they fill gaps (no duplication of dev-guide) +- [ ] Use `templates/operator-pattern-template.md` for structure + +**Common patterns** (create based on need, not mandatory list): +- Status reporting (Available/Progressing/Degraded) β†’ observability principle +- Controller runtime (reconcile loops) β†’ desired-state principle +- Upgrade safety (version skew, Nβ†’N+1) β†’ upgrade-safety principle +- RBAC patterns β†’ security principle + +### Phase 4: Engineering Practices πŸ“š +- [ ] Scan dev-guide/ and guidelines/ to identify what already exists +- [ ] Identify gaps where AI agents need structured guidance +- [ ] Create index.md files that LINK to existing dev-guide content +- [ ] Create NEW practice docs ONLY for gaps (use tables/checklists, not prose) +- [ ] Use `templates/practice-template.md` for structure + +**Common practice areas** (assess each, create if needed): +- Testing pyramid (60/30/10 ratios, when to use each level) +- Security (STRIDE threat modeling, RBAC patterns, secret handling) +- Reliability (SLI/SLO/SLA definitions, degraded-mode patterns) +- Development (API evolution rules, compatibility guidelines) + +### Phase 5: Domain Concepts 🧩 +- [ ] Identify APIs fundamental to understanding OpenShift architecture +- [ ] For each API: document purpose, key fields (YAML), common patterns +- [ ] Use `templates/domain-concept-template.md` for structure +- [ ] Link to `oc explain ` for exhaustive field details + +**Common APIs** (create based on architectural significance): +- Kubernetes core (Pod, Service, CRD), OpenShift platform (ClusterOperator, ClusterVersion), Machine API + +**Don't document**: Every field, component-specific APIs, deprecated APIs + +### Phase 6: Cross-Repo ADRs πŸ“‹ +- [ ] Identify architectural decisions that explain design principles +- [ ] Create ADRs ONLY for cross-repo decisions (not component-specific) +- [ ] Always create: `decisions/index.md` and `decisions/adr-template.md` +- [ ] Use `templates/adr-template.md` for structure + +**Typical ADRs** (create if they explain design philosophy): +- Why etcd, why CVO orchestration, why immutable nodes + +**Don't create**: Component-specific decisions, implementation details, duplicates of dev-guide + +### Phase 7: Workflows & References πŸ”— + +**Workflows** (AI-optimized versions): +- [ ] Create `workflows/enhancement-process.md` - Reformat `guidelines/enhancement_template.md` into tables/steps/YAML +- [ ] Create `workflows/implementing-features.md` - Structured workflow (spec β†’ plan β†’ build β†’ test β†’ review β†’ ship) +- [ ] Create `workflows/index.md` - Navigation + links to guidelines/ for authoritative source + +**References** (pointer-based): +- [ ] Create `references/repo-index.md` with GitHub org search links (not exhaustive lists) +- [ ] Create `references/glossary.md` with core stable terms only (~15-20 terms) +- [ ] Create `references/api-reference.md` with `oc api-resources` pointer +- [ ] Create `references/index.md` for navigation + +**Key principle**: +- Workflows are AI-optimized (tables, checklists, structured) versions of guidelines content +- References use pointers (GitHub links, `oc` commands) not exhaustive lists + +### Phase 7.5: Exec-Plans (Feature Tracking) πŸ“‹ + +**Purpose**: Provide templates and guidance for tracking feature implementation + +- [ ] Create `workflows/exec-plans/README.md` using `templates/workflows/exec-plans-README.md` +- [ ] Create `workflows/exec-plans/template.md` using `templates/workflows/exec-plan-template.md` +- [ ] Explain when to use exec-plans (multi-week features, multi-PR coordination) +- [ ] Explain relationship to enhancements (enhancement = design, exec-plan = implementation tracking) +- [ ] Explain completion workflow (extract to ADRs/architecture, then delete) + +**Key principle**: +- Guidance lives in Tier 1 (generic, used by all repos) +- Actual exec-plans live in Tier 2 component repos (`agentic/exec-plans/active/`) +- Exec-plans are ephemeral - extract knowledge to permanent docs, then delete + +### Phase 8: Validation βœ… +- [ ] Run validation: `bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH"` +- [ ] IF validation fails: Fix issues and re-run +- [ ] Verify all required files exist +- [ ] Verify AGENTS.md is 100-200 lines + +### Phase 9: Report πŸ“Š +- [ ] Report created files count +- [ ] Report validation status +- [ ] Suggest git commit command + +**🚨 DO NOT SKIP ANY CHECKBOX. Complete phases in order.** + +--- + +## What This Skill Creates + +**Principle**: Generate documentation that helps AI agents understand and apply OpenShift design philosophy. + +**Structure:** +``` +AGENTS.md # Master entry point (navigation) +ai-docs/ +β”œβ”€β”€ DESIGN_PHILOSOPHY.md # Core principles (copy from templates) +β”œβ”€β”€ KNOWLEDGE_GRAPH.md # Visual navigation (copy from templates) +β”œβ”€β”€ platform/ # Operator patterns (create based on design principles) +β”œβ”€β”€ practices/ # Cross-cutting concerns (create to fill gaps) +β”œβ”€β”€ domain/ # Core API concepts (create for architectural context) +β”œβ”€β”€ decisions/ # Cross-repo ADRs (create for key decisions) +β”œβ”€β”€ workflows/ # Links to existing dev-guide/guidelines +β”‚ β”œβ”€β”€ exec-plans/ # Exec-plan templates and guidance (Tier 1) +β”‚ β”‚ β”œβ”€β”€ README.md # What/when/how to use exec-plans +β”‚ β”‚ └── template.md # Feature tracking template +β”‚ β”œβ”€β”€ enhancement-process.md +β”‚ └── implementing-features.md +└── references/ # Pointer-based navigation (GitHub links, `oc` commands) +``` + +**What gets automated:** +- `scripts/create-structure.sh`: Creates base directory tree +- `scripts/populate-templates.sh`: Copies DESIGN_PHILOSOPHY.md and KNOWLEDGE_GRAPH.md + +**What you (AI agent) decide:** +- Which platform patterns to document (based on design principles) +- Which domain concepts to document (based on architectural significance) +- Which practices to document (based on gaps in dev-guide) +- Which ADRs to create (based on cross-repo architectural decisions) + +**Do NOT create:** +- Files just to meet a count quota +- Duplicates of dev-guide/guidelines content +- Exhaustive lists that get stale (use pointers instead) +- Component-specific content (belongs in tier-2) + +**Anti-Staleness Strategy:** +- References use GitHub org links and `oc` commands (not exhaustive lists) +- Domain files show key fields only (not every field) +- Workflows link to directories (not specific files) +- Glossary contains only stable core terms (not release-specific features) + +--- + +## File Naming Conventions (MANDATORY) + +**YOU MUST follow these conventions:** + +1. **Index files**: Use `index.md` NOT `README.md` + - βœ… `decisions/index.md`, `platform/operator-patterns/index.md` + - ❌ `decisions/README.md` + +2. **ADR naming**: Use `adr-NNNN-` prefix (4 digits with leading zeros) + - βœ… `decisions/adr-0001-topic-name.md` + - ❌ `decisions/001-topic-name.md` + +3. **Short file names**: Match production conventions + - βœ… `practices/testing/pyramid.md` + - ❌ `practices/testing/testing-pyramid.md` + +4. **Separate distinct concepts**: + - βœ… Create separate files for related but distinct APIs + - ❌ Don't combine multiple APIs in one file + +5. **index.md files**: Brief navigation with 1-sentence descriptions per file + - Example: `## Operator Patterns\n- [status-conditions.md](status-conditions.md) - Available/Progressing/Degraded reporting\n- [controller-runtime.md](controller-runtime.md) - Reconciliation loop patterns` + +--- + +## File Length Targets (Reference Style) + +**Target: 100-400 lines per file** + +- AGENTS.md: **100-200 lines** (aim for concise navigation) +- Operator patterns: **100-400 lines** +- Practices: **150-400 lines** +- Domain concepts: **100-350 lines** + +**Style**: Reference/terse (like man pages), NOT tutorial/verbose. Minimal emojis. + +--- + +## Using Templates + +**Templates are in `$SKILL_DIR/templates/`:** + +### Available Templates + +**Core philosophy** (base content): +- `templates/DESIGN_PHILOSOPHY.md` - Core OpenShift principles (copy/adapt this) +- `templates/KNOWLEDGE_GRAPH.md` - Visual navigation map (copy/adapt this) + +**Entry point** (create in repo root): +- `templates/AGENTS.md` - Master navigation file template + +**Patterns** (templates for structure): +- `templates/operator-pattern-template.md` - Pattern for operator patterns +- `templates/practice-template.md` - Pattern for practices (index files linking to dev-guide) +- `templates/domain-concept-template.md` - Pattern for domain concepts +- `templates/adr-template.md` - Pattern for ADRs + +**How to use templates:** +1. Read template file to understand structure +2. Create new file following same pattern +3. Adapt content to the specific topic +4. Keep similar length and depth + +**Example workflow:** +```bash +# Read template +cat "$SKILL_DIR/templates/operator-patterns/status-conditions.md" + +# Create file following same structure +# Keep: Overview, Key Concepts, Implementation, Best Practices, Examples, References +# Adapt: Topic-specific content +``` + +--- + +## Guidance: What Documentation to Create + +**Principle-Driven Approach**: Create docs that help AI agents apply OpenShift design philosophies, not arbitrary file counts. + +### Entry Points (Always Required) +- `AGENTS.md` - Navigation hub in repo root +- `DESIGN_PHILOSOPHY.md` - Core principles +- `KNOWLEDGE_GRAPH.md` - Visual navigation + +### Platform Patterns (Create Based on Design Philosophy) + +**Ask**: Which patterns help implement the design principles from DESIGN_PHILOSOPHY.md? + +**Common examples** (create if they fill a gap): +- `status-conditions.md` - Implements "Observability by Default" principle +- `controller-runtime.md` - Implements "Desired State" principle +- `upgrade-strategies.md` - Implements "Upgrade Safety" principle +- `webhooks.md` - Implements "API-First Design" principle + +**Don't create**: Patterns already well-documented in dev-guide or controller-runtime docs. + +### Domain Concepts (Create Based on Need) + +**Ask**: Which APIs are fundamental to understanding the architecture? + +**Common examples** (create if needed for AI context): +- `pod.md`, `service.md`, `crds.md` - Kubernetes fundamentals +- `clusteroperator.md`, `clusterversion.md` - OpenShift platform coordination +- `machine.md`, `machineconfig.md` - Immutable infrastructure + +**Don't create**: Every API (use `oc explain` instead). Only document what's architecturally significant. + +### Practices (Create to Fill Gaps) + +**Ask**: What cross-cutting guidance is missing from dev-guide/guidelines? + +**Common examples** (create if gaps exist): +- Testing pyramid, SLI/SLO patterns, threat modeling (STRIDE) +- Link to dev-guide for: enhancement process, git conventions, CI setup + +**Don't create**: Duplicates of existing dev-guide content. + +### ADRs (Create for Cross-Repo Decisions) + +**Ask**: What architectural decisions explain the design philosophy? + +**Common examples**: Why etcd, why CVO orchestration, why immutable nodes + +**Don't create**: Component-specific decisions or implementation details. + +### Workflows (Create AI-Optimized Versions) + +**Ask**: What workflows from guidelines/ need AI-parseable versions? + +**Common examples**: +- **enhancement-process.md** - Reformat `guidelines/enhancement_template.md` (prose β†’ tables/YAML/checklists) +- **implementing-features.md** - Structured workflow (spec β†’ plan β†’ build β†’ test β†’ review β†’ ship) + +**Key**: Same information as guidelines/, but reformatted for AI agents (tables, numbered steps, YAML examples) + +**Don't create**: Verbatim copies of guidelines content. + +--- + +## Validation Criteria + +**Validation focuses on principles, not counts:** + +### Phase 1: Entry Points (Required) +- βœ… AGENTS.md exists at repo root (100-200 lines, navigation-focused) +- βœ… DESIGN_PHILOSOPHY.md exists (defines core principles) +- βœ… KNOWLEDGE_GRAPH.md exists (visual navigation) + +### Phase 2: Design Philosophy Coverage (Assess Gaps) +For each principle in DESIGN_PHILOSOPHY.md, check: +- βœ… Is there documentation to help AI agents apply this principle? +- βœ… Are there examples showing the pattern in action? +- βœ… Are cross-cutting concerns (testing, security, reliability) covered? + +### Phase 3: Avoid Duplication +- βœ… No content duplicating dev-guide/ or guidelines/ (link instead) +- βœ… No component-specific content (belongs in tier-2) +- βœ… References are pointer-based (GitHub org links, `oc` commands) + +### Phase 4: Structural Quality +- βœ… All internal links valid +- βœ… Index files navigate to relevant content +- βœ… Files are reference-style (tables/checklists), not tutorial prose + +**If validation fails:** +- Phase 1 failure: Add missing files to meet minimums +- Phase 2 failure: Fix broken links, adjust line counts, remove component-specific content + +--- + +## What NOT to Include (Forbidden Content) + +**These belong elsewhere:** + +❌ **Component-specific domain concepts** +- Example: Component-specific internal types or controllers +- Note: Platform APIs used across components are OK + +❌ **Component architecture** +- Example: Internal component relationships specific to one repository + +❌ **Component-specific decisions** +- Example: Technology choices unique to one component + +❌ **Component work tracking** +- Example: exec-plans, feature roadmaps + +❌ **Verbatim copies of existing docs** +- Don't copy/paste from guidelines/ or dev-guide/ +- Don't duplicate prose-heavy content without reformatting + +**βœ… What IS allowed:** + +βœ… **AI-optimized versions of guidelines content** - **REFORMAT, don't duplicate** +- Example: Enhancement process β†’ Reformat `guidelines/enhancement_template.md` (prose) into tables/structured format +- Example: API conventions β†’ Extract key rules into decision tables +- Example: PR workflow β†’ Transform narrative into numbered steps + checklists +- **Key**: Same information, AI-parseable format (tables, YAML, checklists) + +βœ… **Generic platform patterns** - **CREATE NEW** +- All operators use these (status conditions, controller runtime, etc.) + +βœ… **Navigation/cross-references** - **LINK** +- Point to authoritative sources in dev-guide/ and guidelines/ + +βœ… **Cross-repo architectural decisions** - **CREATE NEW** +- Affects multiple components (why etcd, why CVO orchestration) + +βœ… **Platform APIs** - **CREATE NEW** +- Used across multiple components (ClusterOperator, MachineConfig) + +--- + +## AGENTS.md Requirements + +**This file is the master entry point. Guidelines:** + +### Length +- **100-200 lines** (aim for concise, table-based navigation) +- Use navigation tables, not tutorial explanations + +### Mandatory Sections + +1. **AI Navigation Section** at TOP (immediately after metadata) + - DON'T read all docs warning + - Explicit examples: + - "Building operator? β†’ DESIGN_PHILOSOPHY.md β†’ controller-runtime.md β†’ status-conditions.md" + - "Writing enhancement? β†’ enhancement-process.md β†’ api-evolution.md β†’ pyramid.md" + - Reference to KNOWLEDGE_GRAPH.md + - Concrete navigation steps (4-5 docs per task) + +2. **Quick Navigation by Role** (table format) +3. **Core Platform Concepts** (table format) +4. **Standard Operator Patterns** (table format) +5. **Engineering Practices** (table format) +6. **Workflows** (link to workflows/ - enhancement process, feature implementation) +7. **Component Repository Index** (link to references/repo-index.md) +8. **Cross-Repo Architectural Decisions** (link to decisions/) +9. **Relationship to Other Documentation** (dev-guide, enhancements, guidelines) +10. **How to Use This Documentation** (for AI agents and humans) + +### Style +- βœ… Navigation-focused with tables +- βœ… Links to detailed docs +- ❌ Tutorial-style explanations +- ❌ Verbose descriptions + +### Validation +```bash +LINE_COUNT=$(wc -l < AGENTS.md) +if [ $LINE_COUNT -gt 220 ] || [ $LINE_COUNT -lt 80 ]; then + echo "⚠️ WARNING: File is $LINE_COUNT lines (target: 100-200)" +fi +``` + +--- + +## Script Execution Reference + +### 1. Discovery Script +```bash +bash "$SKILL_DIR/scripts/discover.sh" "$REPO_PATH" +``` +**Purpose:** Check if ai-docs/ exists, learn naming conventions, identify gaps + +### 2. Structure Creation Script +```bash +bash "$SKILL_DIR/scripts/create-structure.sh" "$REPO_PATH" +``` +**Purpose:** Create empty directory tree (only if ai-docs/ doesn't exist) + +### 3. Populate Templates Script +```bash +bash "$SKILL_DIR/scripts/populate-templates.sh" "$REPO_PATH" +``` +**Purpose:** Copy DESIGN_PHILOSOPHY.md and KNOWLEDGE_GRAPH.md (only if ai-docs/ doesn't exist) + +### 4. Fill Gaps Script +```bash +bash "$SKILL_DIR/scripts/fill-gaps.sh" "$REPO_PATH" +``` +**Purpose:** Identify missing recommended files (only if ai-docs/ already exists) + +### 5. Validation Script +```bash +bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH" +``` +**Purpose:** Comprehensive validation (content minimums + structural checks) + +--- + +## Execution Flow + +``` +User invokes: /platform-docs + +↓ + +Phase 1: Setup + β†’ Find skill directory + β†’ Run discovery script + β†’ Create structure (if new) OR identify gaps (if exists) + β†’ Copy base templates (DESIGN_PHILOSOPHY, KNOWLEDGE_GRAPH) + +↓ + +Phase 2: Create OPENSHIFT_AGENTS.md + β†’ Use template reference + β†’ Validate 150-170 lines + +↓ + +Phase 3-7: Create Documentation + β†’ Platform patterns (use templates/) + β†’ Practices (use templates/) + β†’ Domain concepts (use templates/) + β†’ ADRs, workflows, references + +↓ + +Phase 8: Validation + β†’ Run validation script + β†’ Fix issues if validation fails + +↓ + +Phase 9: Report + β†’ Summary of created files + β†’ Validation status + β†’ Git commit command +``` + +--- + +## Common Mistakes to Avoid + +### ❌ Mistake 1: Skipping Script Execution +**Wrong:** Manually creating directories with `mkdir -p ai-docs/...` +**Right:** Run `create-structure.sh` script + +### ❌ Mistake 2: AGENTS.md Too Long +**Wrong:** 250+ lines with verbose explanations +**Right:** 100-200 lines with navigation tables + +### ❌ Mistake 3: Duplicating Existing Docs +**Wrong:** Creating full `workflows/enhancement-process.md` duplicating guidelines/enhancement_template.md +**Right:** Create `workflows/index.md` that LINKS to guidelines/enhancement_template.md + +### ❌ Mistake 4: Including Component-Specific Content +**Wrong:** Creating files for component-specific internals +**Right:** Keep platform-level only (public APIs, cross-component patterns) + +### ❌ Mistake 5: Skipping Validation +**Wrong:** Not running `validate.sh` at the end +**Right:** Always run validation and fix issues + +### ❌ Mistake 6: Not Using Templates +**Wrong:** Creating files from scratch without looking at templates +**Right:** Read template, understand structure, adapt to topic + +### ❌ Mistake 7: Wrong File Naming +**Wrong:** `decisions/README.md`, `adr-1-topic.md`, `testing-pyramid.md` +**Right:** `decisions/index.md`, `adr-0001-topic.md`, `pyramid.md` + +--- + +## Arguments + +```bash +/platform-docs [--path ] +``` + +**Arguments:** +- `--path `: Path to target repository (default: current directory) +- No args: Create documentation in current directory + +--- + +## When to Use This Skill + +**Use when:** +- Creating AI-optimized documentation structure +- Setting up the ecosystem documentation hub +- The `ai-docs/` directory doesn't exist OR needs to be completed + +**Do NOT use when:** +- The `ai-docs/` directory is already complete and up-to-date + +--- + +## Success Criteria + +**Documentation is complete when:** + +βœ… Entry points exist (AGENTS.md, DESIGN_PHILOSOPHY.md, KNOWLEDGE_GRAPH.md) +βœ… AGENTS.md is 100-200 lines (navigation-focused) +βœ… Each design principle has supporting documentation (patterns, examples) +βœ… No duplication of dev-guide/guidelines content (links instead) +βœ… No component-specific content (belongs in tier-2) +βœ… References are pointer-based (GitHub org links, `oc` commands, not exhaustive lists) +βœ… All files are reference-style (tables/checklists, not tutorial prose) +βœ… Internal links are valid +βœ… Validation script passes (structural checks) + +**Not success criteria:** +❌ File count targets (create what's needed, not to fill quotas) +❌ Covering every API (only architecturally significant ones) +❌ Duplicating existing documentation (link instead) + +--- + +## Final Report Template + +``` +βœ… AI-Optimized Documentation Created + +Location: ai-docs/ + +Entry Points: + βœ… AGENTS.md: XXX lines (target: 100-200) + βœ… DESIGN_PHILOSOPHY.md + βœ… KNOWLEDGE_GRAPH.md + +Documentation Created: + Platform patterns: [X] files + Domain concepts: [X] files + Practices: [X] files + ADRs: [X] files + References: [X] files + +Validation: + βœ… Phase 1: Entry points exist + βœ… Phase 2: Design philosophy coverage adequate + βœ… Phase 3: No duplication detected + βœ… Phase 4: Structural quality checks passed + +Next Steps: + 1. Review documentation for accuracy + 2. Create git commit: + + git add ai-docs/ + git commit -m "Add AI-optimized ecosystem documentation + + Creates ecosystem hub for all OpenShift components. + + Structure: + - Platform patterns (operator patterns, OpenShift specifics) + - Engineering practices (testing, security, reliability) + - Domain concepts (K8s and OpenShift fundamentals) + - Cross-repo ADRs + - Repository index for discovery + + Co-Authored-By: Claude Sonnet 4.5 " +``` + +--- + +**Remember: Complete ALL checklist items. Do NOT skip phases. Use scripts and templates.** diff --git a/plugins/agentic-docs/skills/platform/scripts/create-structure.sh b/plugins/agentic-docs/skills/platform/scripts/create-structure.sh new file mode 100755 index 000000000..7c5d239b8 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/scripts/create-structure.sh @@ -0,0 +1,32 @@ +#!/bin/bash +# Create directory structure for ai-docs/ + +set -e + +REPO_PATH="${1:-.}" + +echo "πŸ“ Creating ai-docs/ directory structure in: $REPO_PATH" +echo "" + +# Create main directory +mkdir -p "$REPO_PATH/ai-docs" + +# Create subdirectories +mkdir -p "$REPO_PATH/ai-docs/platform/operator-patterns" +mkdir -p "$REPO_PATH/ai-docs/platform/openshift-specifics" +mkdir -p "$REPO_PATH/ai-docs/practices/testing" +mkdir -p "$REPO_PATH/ai-docs/practices/security" +mkdir -p "$REPO_PATH/ai-docs/practices/reliability" +mkdir -p "$REPO_PATH/ai-docs/practices/development" +mkdir -p "$REPO_PATH/ai-docs/domain/kubernetes" +mkdir -p "$REPO_PATH/ai-docs/domain/openshift" +mkdir -p "$REPO_PATH/ai-docs/decisions" +mkdir -p "$REPO_PATH/ai-docs/workflows" +mkdir -p "$REPO_PATH/ai-docs/workflows/exec-plans" +mkdir -p "$REPO_PATH/ai-docs/references" + +echo "βœ… Directory structure created:" +tree -d "$REPO_PATH/ai-docs" 2>/dev/null || find "$REPO_PATH/ai-docs" -type d | sed 's|^| |' + +echo "" +echo "Next: Run populate-templates.sh to copy base files" diff --git a/plugins/agentic-docs/skills/platform/scripts/discover.sh b/plugins/agentic-docs/skills/platform/scripts/discover.sh new file mode 100755 index 000000000..3297def3d --- /dev/null +++ b/plugins/agentic-docs/skills/platform/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 practices/testing practices/security practices/reliability practices/development domain/kubernetes domain/openshift decisions workflows 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/platform/scripts/fill-gaps.sh b/plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh new file mode 100755 index 000000000..ae31ae3e2 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh @@ -0,0 +1,96 @@ +#!/bin/bash +# Identify missing recommended files + +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 "πŸ” Identifying gaps in: $AI_DOCS" +echo "" + +GAPS_FOUND=0 + +# Function to check file existence +check_file() { + local file="$1" + local label="${2:-$file}" + + if [ ! -f "$AI_DOCS/$file" ]; then + echo " ❌ Missing: $label" + GAPS_FOUND=1 + else + echo " βœ… $label" + fi +} + +# Function to check directory file count +check_file_count() { + local dir="$1" + local label="$2" + local min_count="$3" + local pattern="${4:-*.md}" + + local count=0 + if [ -d "$AI_DOCS/$dir" ]; then + count=$(find "$AI_DOCS/$dir" -name "$pattern" -type f 2>/dev/null | grep -v index.md | wc -l) + fi + + echo " $label: $count files (need $min_count minimum)" + if [ "$count" -lt "$min_count" ]; then + GAPS_FOUND=1 + fi +} + +# Check critical files +echo "Checking critical files:" +check_file "DESIGN_PHILOSOPHY.md" +check_file "KNOWLEDGE_GRAPH.md" +echo "" + +# Check AGENTS.md at repo root (not in ai-docs/) +if [ ! -f "$REPO_PATH/AGENTS.md" ]; then + echo " ❌ Missing: AGENTS.md (at repo root)" + GAPS_FOUND=1 +else + echo " βœ… AGENTS.md" +fi +echo "" + +# Operator patterns (8 required) +echo "Checking operator patterns (need 8 minimum):" +check_file_count "platform/operator-patterns" "Operator patterns" 8 +echo "" + +# Practices +echo "Checking practices:" +check_file_count "practices/testing" "Testing" 4 +check_file_count "practices/security" "Security" 2 +check_file_count "practices/reliability" "Reliability" 2 +check_file_count "practices/development" "Development" 2 +echo "" + +# Domain concepts +echo "Checking domain concepts:" +check_file_count "domain/kubernetes" "Kubernetes" 3 +check_file_count "domain/openshift" "OpenShift" 4 +echo "" + +# ADRs +echo "Checking ADRs:" +check_file_count "decisions" "ADRs" 3 "adr-*.md" +echo "" + +# Summary +if [ "$GAPS_FOUND" -eq 0 ]; then + echo "βœ… No gaps found - documentation is complete" +else + echo "⚠️ Gaps found - create missing files" +fi + +exit $GAPS_FOUND diff --git a/plugins/agentic-docs/skills/platform/scripts/gap-detection.sh b/plugins/agentic-docs/skills/platform/scripts/gap-detection.sh new file mode 100755 index 000000000..f45796bd7 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/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-docs to add missing content." +fi + +exit 0 diff --git a/plugins/agentic-docs/skills/platform/scripts/populate-templates.sh b/plugins/agentic-docs/skills/platform/scripts/populate-templates.sh new file mode 100755 index 000000000..f2ea4ddff --- /dev/null +++ b/plugins/agentic-docs/skills/platform/scripts/populate-templates.sh @@ -0,0 +1,28 @@ +#!/bin/bash +# Copy core template files to ai-docs/ + +set -e + +REPO_PATH="${1:-.}" +SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +echo "πŸ“„ Copying core template files to: $REPO_PATH/ai-docs" +echo "" + +# Copy the two core files that are generic across all repositories +if [ ! -d "$REPO_PATH/ai-docs" ]; then + echo "❌ Error: ai-docs/ directory does not exist" + echo " Run create-structure.sh first" + exit 1 +fi + +cp "$SKILL_DIR/templates/DESIGN_PHILOSOPHY.md" "$REPO_PATH/ai-docs/" +echo " βœ… Copied DESIGN_PHILOSOPHY.md" + +cp "$SKILL_DIR/templates/KNOWLEDGE_GRAPH.md" "$REPO_PATH/ai-docs/" +echo " βœ… Copied KNOWLEDGE_GRAPH.md" + +echo "" +echo "βœ… Core template files copied successfully" +echo "" +echo "Next: LLM creates remaining documentation files following template patterns" diff --git a/plugins/agentic-docs/skills/platform/scripts/validate.sh b/plugins/agentic-docs/skills/platform/scripts/validate.sh new file mode 100755 index 000000000..96f732e55 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/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 80 ] || [ "$LINE_COUNT" -gt 220 ]; 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/platform/templates/AGENTS.md b/plugins/agentic-docs/skills/platform/templates/AGENTS.md new file mode 100644 index 000000000..6deba2525 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/templates/AGENTS.md @@ -0,0 +1,63 @@ +# Repository Name - Agent Navigation Index + +**Version**: 1.0 | **Docs**: ./ai-docs/ | **Files**: XX | **Lines**: XXXX + +--- + +## CRITICAL: Retrieval Strategy + +**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning. + +When working on OpenShift: +- βœ… **DO**: Read relevant docs from `./ai-docs/` first +- βœ… **DO**: Verify patterns match current APIs +- ❌ **DON'T**: Rely solely on training data +- ❌ **DON'T**: Guess at API structures + +--- + +## Quick Start + +**New to OpenShift?** β†’ Read `./ai-docs/KNOWLEDGE_GRAPH.md` +**Building operator?** β†’ Path: DESIGN_PHILOSOPHY.md β†’ controller-runtime.md β†’ status-conditions.md +**Adding feature?** β†’ Read `./ai-docs/workflows/implementing-features.md` + +--- + +## Compressed Documentation Index + +``` +[Repo Agentic Docs]|root:./ai-docs|XX files, XXXX lines +| +|CRITICAL_READS:{KNOWLEDGE_GRAPH.md,DESIGN_PHILOSOPHY.md} +| +|platform/operator-patterns:{controller-runtime.md,status-conditions.md,...} +|practices/testing:{pyramid.md,e2e-framework.md,...} +|domain/kubernetes:{pod.md,node.md,...} +|domain/openshift:{clusteroperator.md,machine.md,...} +|decisions:{adr-0001-*.md,...} +``` + +--- + +## Task β†’ Docs Quick Map + +| Task | Read These (in order) | +|------|----------------------| +| **Build operator** | DESIGN_PHILOSOPHY.md β†’ controller-runtime.md β†’ status-conditions.md | +| **Add feature** | enhancement-process.md β†’ api-evolution.md β†’ pyramid.md | +| **Debug issue** | observability.md β†’ must-gather.md | + +--- + +## Architecture Overview + +Brief architecture diagram or summary relevant to this repository. + +--- + +## Documentation Principles + +- Progressive disclosure (read 4-5 docs per task, not all) +- Reference style (terse, not tutorial) +- AI-optimized structure diff --git a/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md b/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md new file mode 100644 index 000000000..739716c8a --- /dev/null +++ b/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md @@ -0,0 +1,121 @@ +# OpenShift Design Philosophy + +**Purpose**: Core principles guiding OpenShift architecture and development + +**Last Updated**: YYYY-MM-DD + +--- + +## Table of Contents + +1. [Kubernetes Foundation](#kubernetes-foundation) +2. [The Operator Pattern](#the-operator-pattern) +3. [Immutable Infrastructure](#immutable-infrastructure) +4. [API-First Design](#api-first-design) +5. [Declarative Over Imperative](#declarative-over-imperative) +6. [Upgrade Safety](#upgrade-safety) +7. [Observability by Default](#observability-by-default) + +--- + +## Kubernetes Foundation + +### Desired State vs Current State + +**Core Principle**: Describe what you want, Kubernetes makes it happen. + +``` +User declares: "I want 3 replicas" (Desired State) +Kubernetes sees: "I have 1 replica" (Current State) +Controller: "I'll create 2 more" (Reconciliation) +``` + +**Why This Matters**: +- Self-healing: If a pod dies, controller recreates it +- Idempotent: Applying same config multiple times = same result +- Eventual consistency: System converges to desired state + +--- + +## The Operator Pattern + +**Principle**: Extend Kubernetes with domain-specific knowledge. + +**Pattern**: CustomResourceDefinition + Controller = Operator + +**Benefits**: +- Codifies operational knowledge +- Automates Day 2 operations +- Follows Kubernetes patterns + +--- + +## Immutable Infrastructure + +**Principle**: Nodes are immutable. Changes require reboot. + +**Implementation**: RHCOS + rpm-ostree + Ignition + MachineConfig + +**Benefits**: +- Predictable state +- Easier rollback +- Reduced configuration drift + +--- + +## API-First Design + +**Principle**: Everything is an API resource. + +**Pattern**: All configuration via Kubernetes/OpenShift APIs (no manual SSH, no local files) + +**Benefits**: +- GitOps-friendly +- Auditable +- Version-controlled + +--- + +## Declarative Over Imperative + +**Principle**: Declare intent, not steps. + +**Example**: +- ❌ Imperative: "Run pod1, then pod2, then update service" +- βœ… Declarative: "I want this state" (controller figures out steps) + +--- + +## Upgrade Safety + +**Principle**: Zero-downtime upgrades for platform and workloads. + +**Mechanisms**: +- CVO orchestrates operator upgrades +- Rolling updates for nodes +- Upgrade ordering (etcd β†’ kube β†’ operators) + +--- + +## Observability by Default + +**Principle**: Platform components expose metrics, logs, and health status. + +**Implementation**: +- Prometheus metrics +- Status conditions (Available/Progressing/Degraded) +- Structured logging + +--- + +## Cross-Cutting Concerns + +- **Security by default**: RBAC, SCCs, network policies +- **Multi-tenancy**: Namespace isolation +- **Supportability**: must-gather, diagnostics + +--- + +**See Also**: +- [Operator Patterns](./platform/operator-patterns/) +- [Platform APIs](./domain/openshift/) diff --git a/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md b/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md new file mode 100644 index 000000000..9f669d967 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md @@ -0,0 +1,136 @@ +# OpenShift Knowledge Graph + +**Purpose**: Visual navigation map showing how concepts connect + +**Last Updated**: YYYY-MM-DD + +--- + +## How to Use This + +**Don't read everything.** Follow your task path: +1. Find your task in "I want to..." table below +2. Read only the 4-5 docs in your path +3. Use cross-references as needed + +--- + +## I Want To... + +| Task | Start Here | Then Read | Finally | +|------|-----------|----------|---------| +| **Build an operator** | DESIGN_PHILOSOPHY.md | platform/operator-patterns/controller-runtime.md
platform/operator-patterns/status-conditions.md | domain/openshift/clusteroperator.md | +| **Add a feature** | workflows/index.md (links to enhancement process) | practices/development/index.md (links to API conventions) | practices/testing/index.md | +| **Debug an issue** | practices/reliability/index.md | platform/operator-patterns/must-gather.md | references/repo-index.md | +| **Understand a concept** | DESIGN_PHILOSOPHY.md | domain/kubernetes/ or domain/openshift/ | platform/operator-patterns/ | +| **Find a component** | references/repo-index.md | Component's AGENTS.md | Component's agentic/ docs | + +--- + +## Knowledge Map + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ DESIGN_PHILOSOPHY.md β”‚ +β”‚ (WHY - Core principles, read this first) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PLATFORM/ β”‚ β”‚ DOMAIN/ β”‚ β”‚ PRACTICES/ β”‚ +β”‚ (HOW patterns) β”‚ β”‚ (WHAT) β”‚ β”‚ (WHEN/WHERE) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ operator-patterns/β”‚ β”‚ kubernetes/ β”‚ β”‚ testing/ β”‚ +β”‚ openshift-specificsβ”‚ β”‚ openshift/ β”‚ β”‚ security/ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ reliability/ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ development/ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ DECISIONS/ β”‚ + β”‚ (WHY decisions) β”‚ + β”‚ Cross-repo ADRs β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ REFERENCES/ β”‚ + β”‚ (WHERE to find) β”‚ + β”‚ repo-index, glossary β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## Concept Dependencies + +### Operator Development Path +``` +DESIGN_PHILOSOPHY.md + ↓ +controller-runtime.md (how reconciliation works) + ↓ +status-conditions.md (how to report health) + ↓ +clusteroperator.md (how CVO sees your operator) + ↓ +webhooks.md, rbac-patterns.md, finalizers.md (advanced patterns) +``` + +### API Development Path +``` +DESIGN_PHILOSOPHY.md + ↓ +practices/development/index.md (β†’ links to dev-guide/api-conventions.md) + ↓ +domain/kubernetes/crds.md (CustomResourceDefinition basics) + ↓ +platform/operator-patterns/webhooks.md (validation) +``` + +### Testing Path +``` +practices/testing/index.md (β†’ links to dev-guide/test-conventions.md) + ↓ +Testing pyramid concept + ↓ +E2E framework specifics +``` + +--- + +## Document Types + +| Type | Purpose | Example | +|------|---------|---------| +| **Patterns** | How to implement | platform/operator-patterns/controller-runtime.md | +| **Concepts** | What something is | domain/openshift/clusteroperator.md | +| **Practices** | Links to official docs | practices/testing/index.md β†’ dev-guide/ | +| **Decisions** | Why choices were made | decisions/adr-0001-*.md | +| **References** | Where to find things | references/repo-index.md | + +--- + +## Progressive Disclosure + +**Read in this order**: + +1. **Foundation** (5 min): DESIGN_PHILOSOPHY.md +2. **Your task** (10 min): 2-3 docs from task path above +3. **Details** (20 min): Related patterns/concepts as needed +4. **Reference** (on-demand): Glossary, repo index when needed + +**Total**: ~35 minutes to understand and start, not hours reading everything. + +--- + +## Cross-References + +- Official docs: See ../../dev-guide/ and ../../guidelines/ +- Component repos: See references/repo-index.md +- Enhancement proposals: See ../../enhancements/ diff --git a/plugins/agentic-docs/skills/platform/templates/adr-template.md b/plugins/agentic-docs/skills/platform/templates/adr-template.md new file mode 100644 index 000000000..3583214f3 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/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/platform/templates/domain-concept-template.md b/plugins/agentic-docs/skills/platform/templates/domain-concept-template.md new file mode 100644 index 000000000..6715c83dd --- /dev/null +++ b/plugins/agentic-docs/skills/platform/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 +``` + +## Common Patterns + +### Pattern 1 +```yaml +# Example YAML +``` +**Use case**: When to use this pattern + +### Pattern 2 +```yaml +# Another example +``` +**Use case**: When to use this pattern + +## Lifecycle / Workflow + +``` +Step 1 β†’ Step 2 β†’ Step 3 β†’ Step 4 +``` + +Brief explanation of the flow. + +## Examples + +### Example 1: Common Use Case +```yaml +# Practical example +``` + +### Example 2: Advanced Use Case +```yaml +# Advanced example +``` + +## 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/platform/templates/operator-pattern-template.md b/plugins/agentic-docs/skills/platform/templates/operator-pattern-template.md new file mode 100644 index 000000000..77d386b83 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/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 +} +``` + +## Best Practices + +1. **Practice 1**: Explanation +2. **Practice 2**: Explanation +3. **Practice 3**: Explanation + +## Common Patterns + +### Pattern Variant 1 +```yaml +# YAML or code example +``` + +### Pattern Variant 2 +```go +// Another code example +``` + +## 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/platform/templates/practice-template.md b/plugins/agentic-docs/skills/platform/templates/practice-template.md new file mode 100644 index 000000000..90308bc08 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/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 +``` + +**What to do**: Explanation +**When to use**: Guidance + +### Step 2: Second Action +```bash +# More commands +``` + +## 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 diff --git a/plugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.md b/plugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.md new file mode 100644 index 000000000..912b4d656 --- /dev/null +++ b/plugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.md @@ -0,0 +1,74 @@ +# Feature Name + +**Status**: Active | Completed +**Start Date**: YYYY-MM-DD +**Target Release**: X.Y +**Enhancement**: [Link to enhancement proposal] +**Component**: [Component Name] + +## Summary + +Brief 1-2 sentence summary of what feature is being implemented. + +## Goals + +- Goal 1 +- Goal 2 +- Goal 3 + +## Non-Goals + +- Non-goal 1 +- Non-goal 2 + +## Implementation Plan + +### Phase 1: [Phase Name] +**Timeline**: Week 1-2 + +Tasks: +- [ ] Task 1 +- [ ] Task 2 +- [ ] Task 3 + +**PRs**: +- [ ] PR #XXX - Description + +### Phase 2: [Phase Name] +**Timeline**: Week 3-4 + +Tasks: +- [ ] Task 1 +- [ ] Task 2 + +**PRs**: +- [ ] PR #XXX - Description + +## Testing Strategy + +- Unit tests: [Coverage plan] +- Integration tests: [What to test] +- E2E tests: [Scenarios] + +## Dependencies + +- Dependency 1 (internal/external) +- Dependency 2 + +## Risks + +| Risk | Mitigation | +|------|-----------| +| Risk 1 | Mitigation plan | +| Risk 2 | Mitigation plan | + +## Completion Criteria + +- [ ] All PRs merged +- [ ] Tests passing +- [ ] Documentation updated +- [ ] Feature flagged (if applicable) + +## Notes + +Additional notes, decisions, or context discovered during implementation. diff --git a/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md b/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md new file mode 100644 index 000000000..e92d5711f --- /dev/null +++ b/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md @@ -0,0 +1,188 @@ +# Execution Plans (Exec-Plans) + +Track active feature implementations across component repositories. + +## What are Exec-Plans? + +Exec-plans are **ephemeral** feature tracking documents that bridge enhancements (high-level design) and implementation (PRs and code). They help: + +- Track multi-PR features +- Coordinate work across weeks/months +- Capture implementation decisions during development + +**Important**: Exec-plans are temporary. When complete, extract permanent knowledge into proper docs (ADRs, architecture docs) and delete the exec-plan. + +## When to Create an Exec-Plan + +**DO create** an exec-plan when: +- βœ… Implementing a new feature from an enhancement +- βœ… Major refactoring or architectural change +- βœ… Cross-component feature (your component's portion) +- βœ… Multi-week engineering effort (3+ weeks) +- βœ… Feature requires coordination across multiple PRs + +**DON'T create** an exec-plan for: +- ❌ Bug fixes (unless major architectural fix) +- ❌ Minor refactoring +- ❌ Documentation-only changes +- ❌ Single-PR features +- ❌ Routine maintenance + +## Usage + +### Starting a New Feature + +```bash +# In your component repo: component-repo/agentic/exec-plans/ + +# Copy template from Tier 1 +curl -O https://raw.githubusercontent.com/openshift/enhancements/master/ai-docs/workflows/exec-plans/template.md + +# Move to active +mv template.md active/feature-name.md + +# Fill in the template +# - Summary: What you're building +# - Goals/Non-Goals: Scope boundaries +# - Implementation Plan: Phases with tasks and PRs +# - Testing Strategy: How you'll test it +# - Dependencies: What you need from other teams +# - Risks: What could go wrong +``` + +### During Implementation + +Update the exec-plan as you work: +- Check off completed tasks: `- [x] Task completed` +- Link PRs: `- [x] PR #123 - Add controller logic` +- Document decisions in Notes section +- Update timelines if they slip + +### When Implementation Completes + +**Extract permanent knowledge**, then delete the exec-plan: + +```bash +# 1. Review the exec-plan for permanent knowledge +cat active/feature-name.md + +# 2. Extract to permanent docs: + +# If architectural decision was made: +cp agentic/decisions/adr-template.md agentic/decisions/adr-NNNN-decision-name.md +# Document the decision in the ADR + +# If architecture changed: +# Update agentic/architecture/components.md with new structure + +# If new CRD was added: +# Already documented in agentic/domain/crd-name.md + +# 3. Delete the exec-plan (it's in git history if needed) +git rm active/feature-name.md +git commit -m "Complete feature-name implementation + +Architectural decisions documented in adr-NNNN-*.md +Architecture changes in architecture/components.md +" +``` + +**Why delete?** +- Exec-plans are ephemeral tracking, not permanent docs +- Git history preserves it if needed: `git log --all -- agentic/exec-plans/active/feature-name.md` +- Permanent knowledge belongs in ADRs and architecture docs + +## Relationship to Other Docs + +**Enhancement (Tier 1)**: +- Where: `openshift/enhancements` +- What: High-level design, API, user stories +- When: Before implementation starts +- Scope: Platform-wide, cross-repo + +**Exec-Plan (Tier 2)**: +- Where: Component repository (`agentic/exec-plans/active/`) +- What: Implementation tracking, PR coordination, decisions +- When: During implementation +- Scope: Component-specific + +**PRs**: +- Where: GitHub pull requests +- What: Actual code changes +- When: Implementation + +**Flow**: Enhancement β†’ Exec-Plan β†’ PRs β†’ Code + +## Completion Decision Matrix + +When feature is complete, ask: + +| Question | Yes | Action | +|----------|-----|--------| +| Did we make an architectural decision? | βœ… | Create ADR in `agentic/decisions/adr-NNNN-*.md` | +| Did component architecture change? | βœ… | Update `agentic/architecture/components.md` | +| Did we add a new CRD? | βœ… | Already in `agentic/domain/*.md` | +| Did we add new components/controllers? | βœ… | Update `agentic/architecture/components.md` | +| Just implementation (no architecture)? | βœ… | Delete exec-plan (it's in git history) | + +**Then**: Delete the exec-plan. It's ephemeral tracking, not permanent documentation. + +## Example Workflow + +### Example: Custom Kernels Feature + +1. **New Enhancement Approved** + - Enhancement: "Add support for custom kernels" + - Create: `agentic/exec-plans/active/custom-kernels.md` + +2. **During Development** (Week 1-4) + - Update exec-plan with PRs + - Document decisions in Notes: "decided to use kernel args instead of kernel modules" + - Track dependencies: "waiting for CVO changes" + +3. **Feature Complete** + + **Extract permanent knowledge**: + ```bash + # Architectural decision made during development + vim agentic/decisions/adr-0004-kernel-args-vs-modules.md + # Document: Why kernel args? Performance, compatibility, rollback + + # Architecture changed (new controller added) + vim agentic/architecture/components.md + # Add: KernelController - manages kernel arguments via MachineConfig + + # New CRD added + vim agentic/domain/kernelconfig.md + # Already documented during development + + # Delete ephemeral exec-plan + git rm agentic/exec-plans/active/custom-kernels.md + git commit -m "Complete custom kernels feature + + Architectural decision in adr-0004-kernel-args-vs-modules.md + Architecture updated in components.md + KernelConfig CRD documented in domain/kernelconfig.md + " + ``` + +4. **Result** + - βœ… Permanent knowledge in proper docs (ADR, architecture, domain) + - βœ… Exec-plan deleted (ephemeral tracking done) + - βœ… Git history preserves exec-plan if needed for historical context + +## Tips + +**Keep it lean**: Exec-plans are not requirements docs. Link to the enhancement for design details. + +**Update regularly**: Keep the exec-plan current as you implement. It's most valuable when actively maintained. + +**Document decisions in Notes**: Capture implementation decisions during development. When complete, move architectural decisions to ADRs. + +**Extract, then delete**: When done, extract permanent knowledge into proper docs, then delete the exec-plan. Git history preserves it if needed. + +## See Also + +- [Enhancement Process](../enhancement-process.md) +- [Exec-Plan Template](./template.md) +- [Component Documentation Guide](https://github.com/openshift/ai-helpers/tree/master/plugins/agentic-docs) 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..4a9cab532 --- /dev/null +++ b/plugins/agentic-docs/skills/update-platform-docs/SKILL.md @@ -0,0 +1,365 @@ +--- +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:** +- ai-docs/ doesn't exist yet (use `/platform-docs` instead) +- You want to completely regenerate all docs + +## 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 (if not, suggest `/platform-docs`) +- [ ] 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 ≀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 ≀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. Update structure in platform/scripts/create-structure.sh +7. 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` +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 ≀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 ] +``` + +**Arguments:** +- `--path `: Path to enhancements repository (default: current directory) +- No args: Update documentation in current directory + +## Prerequisites + +**Before running:** +1. βœ… ai-docs/ already exists (if not, use `/platform-docs`) +2. βœ… You're in openshift/enhancements repository +3. βœ… You know what you want to add/update + +**If ai-docs/ doesn't exist:** +```bash +# First create base documentation +/platform-docs + +# Then use /update-platform-docs for incremental changes +``` + +## Success Output + +``` +βœ… 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) + βœ… Updated: skills/platform/scripts/create-structure.sh + +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: Using When ai-docs/ Doesn't Exist +**Wrong:** Running `/update-platform-docs` on fresh repo +**Right:** Run `/platform-docs` first, then use `/update-platform-docs` + +### ❌ Mistake 2: Making AGENTS.md Too Long +**Wrong:** Adding verbose descriptions to AGENTS.md +**Right:** Keep compressed, table-based navigation only + +### ❌ Mistake 3: Not Updating Index Files +**Wrong:** Creating new file without updating parent index.md +**Right:** Always update corresponding index.md + +### ❌ Mistake 4: Inconsistent Naming +**Wrong:** Creating `README.md` or `adr-1-topic.md` +**Right:** Use `index.md` and `adr-0001-topic.md` + +### ❌ Mistake 5: Duplicating Content +**Wrong:** Copying content from dev-guide/guidelines +**Right:** Link to authoritative source or reformat for AI agents + +## See Also + +- `/platform-docs` - Create platform documentation from scratch +- [Platform SKILL.md](../SKILL.md) - Full platform docs creation guide +- [Validation Script](../scripts/validate.sh) - Structure validation 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 120000 index 000000000..daab30213 --- /dev/null +++ b/plugins/agentic-docs/skills/update-platform-docs/scripts/discover.sh @@ -0,0 +1 @@ +../../platform/scripts/discover.sh \ No newline at end of file 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 120000 index 000000000..7a4a893cd --- /dev/null +++ b/plugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.sh @@ -0,0 +1 @@ +../../platform/scripts/gap-detection.sh \ No newline at end of file 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 120000 index 000000000..ea811c456 --- /dev/null +++ b/plugins/agentic-docs/skills/update-platform-docs/scripts/validate.sh @@ -0,0 +1 @@ +../../platform/scripts/validate.sh \ No newline at end of file diff --git a/plugins/agentic-docs/skills/update-platform-docs/templates b/plugins/agentic-docs/skills/update-platform-docs/templates new file mode 120000 index 000000000..066d4e3c0 --- /dev/null +++ b/plugins/agentic-docs/skills/update-platform-docs/templates @@ -0,0 +1 @@ +../platform/templates \ No newline at end of file From 198f3c215abe4e38cf9ffa9a56ef9d581f8de731 Mon Sep 17 00:00:00 2001 From: Prashanth684 Date: Wed, 29 Apr 2026 10:59:38 -0700 Subject: [PATCH 2/3] Add agentic-docs plugin: tier-2 component documentation Introduces tier-2 lean component documentation skill for creating structured component-level documentation in OpenShift repositories. Skills: /agentic-docs:component (/component-docs): Creates tier-2 lean component documentation with: - Component-specific CRDs and architecture only - Pointers to tier-1 for generic patterns - Component ADRs and exec-plan tracking - AGENTS.md entry point - DEVELOPMENT.md and TESTING.md guides - Domain concepts and ecosystem maps --- docs/data.json | 12 +- plugins/agentic-docs/README.md | 8 +- .../agentic-docs/skills/component/SKILL.md | 528 ++++++++++++++++++ .../component/scripts/create-structure.sh | 20 + .../skills/component/scripts/validate.sh | 353 ++++++++++++ .../component/templates/AGENTS-template.md | 63 +++ .../templates/DEVELOPMENT-template.md | 199 +++++++ .../component/templates/TESTING-template.md | 297 ++++++++++ .../component/templates/adr-template.md | 50 ++ .../templates/domain-concept-template.md | 63 +++ .../component/templates/ecosystem-template.md | 83 +++ .../templates/exec-plans-README-template.md | 31 + plugins/agentic-docs/skills/platform/SKILL.md | 46 +- .../skills/platform/scripts/discover.sh | 2 +- .../skills/platform/scripts/fill-gaps.sh | 2 +- .../skills/platform/scripts/gap-detection.sh | 2 +- .../skills/platform/scripts/validate.sh | 2 +- .../skills/platform/templates/AGENTS.md | 4 +- .../platform/templates/DESIGN_PHILOSOPHY.md | 2 +- .../platform/templates/KNOWLEDGE_GRAPH.md | 20 +- .../templates/domain-concept-template.md | 14 +- .../templates/operator-pattern-template.md | 6 +- .../platform/templates/practice-template.md | 4 +- .../templates/workflows/exec-plans-README.md | 34 +- .../skills/update-platform-docs/SKILL.md | 22 +- 25 files changed, 1782 insertions(+), 85 deletions(-) create mode 100644 plugins/agentic-docs/skills/component/SKILL.md create mode 100755 plugins/agentic-docs/skills/component/scripts/create-structure.sh create mode 100755 plugins/agentic-docs/skills/component/scripts/validate.sh create mode 100644 plugins/agentic-docs/skills/component/templates/AGENTS-template.md create mode 100644 plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md create mode 100644 plugins/agentic-docs/skills/component/templates/TESTING-template.md create mode 100644 plugins/agentic-docs/skills/component/templates/adr-template.md create mode 100644 plugins/agentic-docs/skills/component/templates/domain-concept-template.md create mode 100644 plugins/agentic-docs/skills/component/templates/ecosystem-template.md create mode 100644 plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md diff --git a/docs/data.json b/docs/data.json index 9d6c67ef3..04e62c417 100644 --- a/docs/data.json +++ b/docs/data.json @@ -1830,10 +1830,20 @@ "hooks": [], "name": "agentic-docs", "skills": [ + { + "description": "Create lean tier-2 component documentation for OpenShift repositories", + "id": "component", + "name": "component-docs" + }, { "description": "Create AI-optimized platform documentation for openshift/enhancements", "id": "platform", - "name": "platform" + "name": "platform-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" diff --git a/plugins/agentic-docs/README.md b/plugins/agentic-docs/README.md index 699af9c75..94608c536 100644 --- a/plugins/agentic-docs/README.md +++ b/plugins/agentic-docs/README.md @@ -7,7 +7,7 @@ AI-optimized OpenShift documentation with progressive disclosure, reference styl **Tier 1: Platform Hub** (`openshift/enhancements/ai-docs/`) Generic patterns, testing, security, K8s/OpenShift fundamentals, cross-repo ADRs. ~34 files, 4.4k lines. -**Tier 2: Component Repos** (`{component}/agentic/`) +**Tier 2: Component Repos** (`{component}/ai-docs/`) Component CRDs, architecture, local ADRs, exec-plans. Links to Tier 1. ~15 files, 2.5k lines (58% leaner). ## Skills @@ -22,12 +22,12 @@ cd /path/to/openshift/enhancements Creates AGENTS.md (navigation) + ai-docs/ with: platform patterns (controller-runtime, webhooks, finalizers, RBAC, must-gather), domain concepts (K8s/OpenShift APIs), practices (testing, security, reliability), cross-repo ADRs, workflows (exec-plans, enhancement process), and references (repo-index, glossary, API pointers). -### `/update-docs` +### `/update-platform-docs` Incrementally update Tier 1 docs with automatic gap detection. ```bash cd /path/to/openshift/enhancements -/update-docs +/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 when ai-docs/ exists (otherwise use `/platform-docs`). @@ -40,7 +40,7 @@ cd /path/to/component-repository /component-docs ``` -Creates AGENTS.md + agentic/ with: component CRDs only, architecture, component ADRs, exec-plans, ecosystem links to Tier 1, development/testing guides. Excludes generic patterns (lives in Tier 1). Example: [machine-config-operator/agentic](https://github.com/openshift/machine-config-operator/tree/master/agentic). +Creates AGENTS.md + ai-docs/ with: component CRDs only, architecture, component ADRs, exec-plans, ecosystem links to Tier 1, development/testing guides. Excludes generic patterns (lives in Tier 1). Example: [machine-config-operator/ai-docs](https://github.com/openshift/machine-config-operator/tree/master/ai-docs). ## Development diff --git a/plugins/agentic-docs/skills/component/SKILL.md b/plugins/agentic-docs/skills/component/SKILL.md new file mode 100644 index 000000000..ed5c86aee --- /dev/null +++ b/plugins/agentic-docs/skills/component/SKILL.md @@ -0,0 +1,528 @@ +--- +name: component-docs +description: Create lean tier-2 component documentation for OpenShift repositories +trigger: explicit +model: sonnet +--- + +# Component Documentation Creator + +Creates lean tier-2 agentic documentation for OpenShift component repositories. + +**Philosophy**: Component docs contain ONLY component-specific knowledge. Generic platform patterns live in tier-1 (openshift/enhancements/ai-docs/). + +## Two-Tier Architecture + +### Tier 1: Platform Hub (openshift/enhancements/ai-docs/) +**Contains**: Operator patterns, testing practices, security guidelines, Kubernetes/OpenShift fundamentals, cross-repo ADRs + +### Tier 2: Component Repos (LEAN) +**Contains**: Component-specific CRDs, component architecture, component ADRs, exec-plans + +**Decision Rule**: "Would another repo need to duplicate this?" +- YES β†’ Tier 1 (platform) +- NO β†’ Tier 2 (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 Tier 1 guidance + β”œβ”€β”€ references/ + β”‚ └── ecosystem.md # Links to Tier 1 (CRITICAL) + β”œβ”€β”€ [COMPONENT]_DEVELOPMENT.md + └── [COMPONENT]_TESTING.md +```text + +## What NOT to Include (lives in Tier 1) + +❌ 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" -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 Tier 1 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 Tier 1 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 Tier 1) + +### Phase 6: Exec-Plans +- [ ] Create exec-plans/active/ directory (for component-specific exec-plans) +- [ ] Create exec-plans/README.md with pointer to Tier 1 guidance +- [ ] Link to Tier 1: `https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/` +- [ ] NO templates or detailed guidance (lives in Tier 1) + +### Phase 7: Ecosystem References +- [ ] Create references/ecosystem.md +- [ ] Link to Tier 1 operator patterns +- [ ] Link to Tier 1 testing practices +- [ ] Link to Tier 1 security practices +- [ ] Link to Tier 1 Kubernetes/OpenShift fundamentals +- [ ] Link to Tier 1 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 Tier 1 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 Tier 1 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 Tier 1 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, tier) +2. Tier 1 reference (link to ecosystem hub) +3. Component purpose (what is it?) +4. Core components (brief) +5. Documentation structure (compressed) +6. Knowledge graph (visual) +7. Tier 1 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 +**Documentation Tier**: 2 (Component-specific) + +> **Generic Platform Patterns**: See [Tier 1 Hub](https://github.com/openshift/enhancements/tree/master/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 + +## Tier 1 Links + +**Patterns**: [Operator](tier1-link) | [Testing](tier1-link) | [Security](tier1-link) + +## 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 (Tier 1, 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 Tier 1 (platform-docs) +- **Templates & Usage**: See [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/) +- **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 Tier 1 guidance +```text + +**What component-docs creates**: +- `active/` directory (empty, ready for exec-plans) +- `README.md` with pointer to Tier 1 + +**What component-docs does NOT create**: +- ❌ Templates (live in Tier 1) +- ❌ Detailed guidance (lives in Tier 1) +- ❌ `completed/` directory (exec-plans are deleted after extracting knowledge) + +**Workflow**: See [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/README.md) + +## Ecosystem References + +**File**: `references/ecosystem.md` + +**Links to Tier 1**: +- 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 Tier 1 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 Tier 1 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 Tier 1 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 +- Tier 1 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 Tier 1 operator patterns +- Links to Tier 1 testing practices +- Links to Tier 1 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 Tier 1 planned links +- Links to upstream documentation are valid and current + +## Anti-Patterns + +### ❌ DON'T duplicate Tier 1 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 [Tier 1](tier1-link) + +## Component Test Suites +[90 lines component-specific] +```text + +### ❌ DON'T explain generic patterns + +**Wrong**: Explaining controller-runtime in component docs +**Right**: Link to Tier 1, document component-specific usage + +### ❌ DON'T create cross-repo ADRs + +**Wrong**: ADR about etcd in component repo +**Right**: ADR about etcd in Tier 1 + +## 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 Tier 1 PR (not 60+ component PRs) + +## Prerequisites + +**Before running**: +1. βœ… Tier 1 exists at openshift/enhancements/ai-docs/ +2. βœ… Repository is OpenShift component +3. βœ… You understand two-tier architecture + +**If Tier 1 doesn't exist**: Create it first using `/platform-docs` + +## Arguments + +```bash +/component-docs [--path ] +```text + +**Arguments**: +- `--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 Tier 1 links + βœ… Development: COMPONENT_DEVELOPMENT.md + βœ… Testing: COMPONENT_TESTING.md + +Validation: + βœ… AGENTS.md at root (80-100 lines) + βœ… No generic duplication + βœ… Tier 1 links present + βœ… Component-specific content only + +Tier 1 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 + +- `/platform-docs` - Create Tier 1 platform documentation +- [Tier 1 Hub](https://github.com/openshift/enhancements/tree/master/ai-docs) +- [MCO Example](https://github.com/openshift/machine-config-operator/tree/master/ai-docs) diff --git a/plugins/agentic-docs/skills/component/scripts/create-structure.sh b/plugins/agentic-docs/skills/component/scripts/create-structure.sh new file mode 100755 index 000000000..681ab6061 --- /dev/null +++ b/plugins/agentic-docs/skills/component/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/scripts/validate.sh b/plugins/agentic-docs/skills/component/scripts/validate.sh new file mode 100755 index 000000000..373825f02 --- /dev/null +++ b/plugins/agentic-docs/skills/component/scripts/validate.sh @@ -0,0 +1,353 @@ +#!/bin/bash +# +# Component Documentation Validator +# +# Validates component-tier 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 Tier 1 references +if grep -q "Tier 1" "$REPO_PATH/AGENTS.md" || grep -q "openshift/enhancements" "$REPO_PATH/AGENTS.md"; then + echo " βœ… Tier 1 ecosystem references found" +else + echo " ⚠️ No Tier 1 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 "Tier 1" "$REPO_PATH/ai-docs/references/ecosystem.md"; then + echo " Contains Tier 1 links βœ…" + else + echo " ⚠️ No Tier 1 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 Tier 1)" + 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/templates/AGENTS-template.md b/plugins/agentic-docs/skills/component/templates/AGENTS-template.md new file mode 100644 index 000000000..e34dbe5c4 --- /dev/null +++ b/plugins/agentic-docs/skills/component/templates/AGENTS-template.md @@ -0,0 +1,63 @@ +# Component Name - Agentic Documentation + +**Component**: [Component Full Name] +**Repository**: openshift/[repo-name] +**Documentation Tier**: 2 (Component-specific) + +> **Generic Platform Patterns**: See [Tier 1 Ecosystem Hub](https://github.com/openshift/enhancements/tree/master/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 Tier 1 +β”œβ”€β”€ [COMPONENT]_DEVELOPMENT.md # Component dev workflows +└── [COMPONENT]_TESTING.md # Component test suites +```text + +**Exec-Plans**: Use `active/` for new features. See [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans). + +**Platform Patterns (Tier 1)**: [Operator](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns) | [Testing](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) | [Security](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/security) + +## Knowledge Graph + +```text + [AGENTS.md] ← Start here + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + [domain/] [architecture/] [decisions/] + CRD concepts Component design ADR history + β”‚ β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + [references/ecosystem] + Links to Tier 1 +```text + +**AI Agent Path**: domain/ β†’ architecture/ β†’ decisions/ β†’ [COMPONENT]_DEVELOPMENT.md + +## External References + +- [Product Docs](https://docs.openshift.com/) | [Related Project](https://github.com/...) + +--- + +**Tier 1 Hub**: https://github.com/openshift/enhancements/tree/master/ai-docs diff --git a/plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md b/plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md new file mode 100644 index 000000000..71f22187f --- /dev/null +++ b/plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md @@ -0,0 +1,199 @@ +# [Component Name] - Development Guide + +> **Generic Development Practices**: See [Tier 1 Development Practices](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/development) 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 [Tier 1](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns/controller-runtime.md) + +### 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 [Tier 1 Release Process](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/development). + +## 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) +- [Tier 1 Development Practices](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/development) diff --git a/plugins/agentic-docs/skills/component/templates/TESTING-template.md b/plugins/agentic-docs/skills/component/templates/TESTING-template.md new file mode 100644 index 000000000..d059ab25b --- /dev/null +++ b/plugins/agentic-docs/skills/component/templates/TESTING-template.md @@ -0,0 +1,297 @@ +# [Component Name] - Testing Guide + +> **Generic Testing Practices**: See [Tier 1 Testing Practices](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) 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 [Tier 1 Controller Runtime](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns/controller-runtime.md) + +#### 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 [Tier 1 E2E Framework](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) + +### 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) +- [Tier 1 Testing Practices](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) diff --git a/plugins/agentic-docs/skills/component/templates/adr-template.md b/plugins/agentic-docs/skills/component/templates/adr-template.md new file mode 100644 index 000000000..35fefc8e7 --- /dev/null +++ b/plugins/agentic-docs/skills/component/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 [Tier 1 ADRs](https://github.com/openshift/enhancements/tree/master/ai-docs/decisions). + +## 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 +- [Tier 1 ADRs](https://github.com/openshift/enhancements/tree/master/ai-docs/decisions) for cross-repo decisions diff --git a/plugins/agentic-docs/skills/component/templates/domain-concept-template.md b/plugins/agentic-docs/skills/component/templates/domain-concept-template.md new file mode 100644 index 000000000..c537d733f --- /dev/null +++ b/plugins/agentic-docs/skills/component/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: [Tier 1](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns) +- Status conditions: [Tier 1](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns/status-conditions.md) + +## Related Concepts + +- [Other Resource](./other-resource.md) - Related component resource diff --git a/plugins/agentic-docs/skills/component/templates/ecosystem-template.md b/plugins/agentic-docs/skills/component/templates/ecosystem-template.md new file mode 100644 index 000000000..ca1e67d44 --- /dev/null +++ b/plugins/agentic-docs/skills/component/templates/ecosystem-template.md @@ -0,0 +1,83 @@ +# Tier 1 Ecosystem References + +This document links to generic OpenShift/Kubernetes patterns in the Tier 1 ecosystem hub. The component inherits these platform-wide patterns and practices. + +## Operator Patterns + +**Location**: [ai-docs/platform/operator-patterns/](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns) + +- **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/](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) + +- **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/](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/security) + +- **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/](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/reliability) + +- **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/](https://github.com/openshift/enhancements/tree/master/ai-docs/domain/kubernetes) + +- **Pod**: Pod lifecycle, container specs +- **CRDs**: CustomResourceDefinition patterns + +**Component Usage**: +- [Describe how component uses Kubernetes fundamentals] + +## OpenShift Fundamentals + +**Location**: [ai-docs/domain/openshift/](https://github.com/openshift/enhancements/tree/master/ai-docs/domain/openshift) + +- **ClusterOperator**: Cluster operator status reporting +- **ClusterVersion**: Platform upgrade orchestration + +**Component Usage**: +- [Describe how component integrates with platform] + +## Cross-Repository ADRs + +**Location**: [ai-docs/decisions/](https://github.com/openshift/enhancements/tree/master/ai-docs/decisions) + +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 Tier 1 (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/templates/exec-plans-README-template.md b/plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md new file mode 100644 index 000000000..d6dc0f310 --- /dev/null +++ b/plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md @@ -0,0 +1,31 @@ +# Execution Plans + +> **Exec-Plans Guidance**: See [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/) 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 Tier 1 +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 [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/README.md) for complete documentation. diff --git a/plugins/agentic-docs/skills/platform/SKILL.md b/plugins/agentic-docs/skills/platform/SKILL.md index 12c87ca21..31accb320 100644 --- a/plugins/agentic-docs/skills/platform/SKILL.md +++ b/plugins/agentic-docs/skills/platform/SKILL.md @@ -101,7 +101,7 @@ Creates AI-optimized platform documentation in `openshift/enhancements` reposito **Key principle**: - Guidance lives in Tier 1 (generic, used by all repos) -- Actual exec-plans live in Tier 2 component repos (`agentic/exec-plans/active/`) +- Actual exec-plans live in Tier 2 component repos (`ai-docs/exec-plans/active/`) - Exec-plans are ephemeral - extract knowledge to permanent docs, then delete ### Phase 8: Validation βœ… @@ -124,7 +124,7 @@ Creates AI-optimized platform documentation in `openshift/enhancements` reposito **Principle**: Generate documentation that helps AI agents understand and apply OpenShift design philosophy. **Structure:** -``` +```text AGENTS.md # Master entry point (navigation) ai-docs/ β”œβ”€β”€ DESIGN_PHILOSOPHY.md # Core principles (copy from templates) @@ -140,7 +140,7 @@ ai-docs/ β”‚ β”œβ”€β”€ enhancement-process.md β”‚ └── implementing-features.md └── references/ # Pointer-based navigation (GitHub links, `oc` commands) -``` +```text **What gets automated:** - `scripts/create-structure.sh`: Creates base directory tree @@ -170,9 +170,10 @@ ai-docs/ **YOU MUST follow these conventions:** -1. **Index files**: Use `index.md` NOT `README.md` +1. **Index files**: Use `index.md` NOT `README.md` (exception: `workflows/exec-plans/README.md`) - βœ… `decisions/index.md`, `platform/operator-patterns/index.md` - ❌ `decisions/README.md` + - βœ… `workflows/exec-plans/README.md` (exception: exec-plans uses README for GitHub convention) 2. **ADR naming**: Use `adr-NNNN-` prefix (4 digits with leading zeros) - βœ… `decisions/adr-0001-topic-name.md` @@ -237,7 +238,7 @@ cat "$SKILL_DIR/templates/operator-patterns/status-conditions.md" # Create file following same structure # Keep: Overview, Key Concepts, Implementation, Best Practices, Examples, References # Adapt: Topic-specific content -``` +```text --- @@ -350,8 +351,9 @@ For each principle in DESIGN_PHILOSOPHY.md, check: ❌ **Component-specific decisions** - Example: Technology choices unique to one component -❌ **Component work tracking** -- Example: exec-plans, feature roadmaps +❌ **Component-specific work tracking content** +- Example: component-local sprint plans, team-specific roadmaps +- Note: Tier-1 exec-plan guidance/templates are allowed; only component-local instances belong in tier-2 repos ❌ **Verbatim copies of existing docs** - Don't copy/paste from guidelines/ or dev-guide/ @@ -416,10 +418,10 @@ For each principle in DESIGN_PHILOSOPHY.md, check: ### Validation ```bash LINE_COUNT=$(wc -l < AGENTS.md) -if [ $LINE_COUNT -gt 220 ] || [ $LINE_COUNT -lt 80 ]; then +if [ $LINE_COUNT -gt 200 ] || [ $LINE_COUNT -lt 100 ]; then echo "⚠️ WARNING: File is $LINE_COUNT lines (target: 100-200)" fi -``` +```text --- @@ -428,38 +430,38 @@ fi ### 1. Discovery Script ```bash bash "$SKILL_DIR/scripts/discover.sh" "$REPO_PATH" -``` +```text **Purpose:** Check if ai-docs/ exists, learn naming conventions, identify gaps ### 2. Structure Creation Script ```bash bash "$SKILL_DIR/scripts/create-structure.sh" "$REPO_PATH" -``` +```text **Purpose:** Create empty directory tree (only if ai-docs/ doesn't exist) ### 3. Populate Templates Script ```bash bash "$SKILL_DIR/scripts/populate-templates.sh" "$REPO_PATH" -``` +```text **Purpose:** Copy DESIGN_PHILOSOPHY.md and KNOWLEDGE_GRAPH.md (only if ai-docs/ doesn't exist) ### 4. Fill Gaps Script ```bash bash "$SKILL_DIR/scripts/fill-gaps.sh" "$REPO_PATH" -``` +```text **Purpose:** Identify missing recommended files (only if ai-docs/ already exists) ### 5. Validation Script ```bash bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH" -``` +```text **Purpose:** Comprehensive validation (content minimums + structural checks) --- ## Execution Flow -``` +```text User invokes: /platform-docs ↓ @@ -472,7 +474,7 @@ Phase 1: Setup ↓ -Phase 2: Create OPENSHIFT_AGENTS.md +Phase 2: Create AGENTS.md β†’ Use template reference β†’ Validate 150-170 lines @@ -496,7 +498,7 @@ Phase 9: Report β†’ Summary of created files β†’ Validation status β†’ Git commit command -``` +```text --- @@ -511,8 +513,8 @@ Phase 9: Report **Right:** 100-200 lines with navigation tables ### ❌ Mistake 3: Duplicating Existing Docs -**Wrong:** Creating full `workflows/enhancement-process.md` duplicating guidelines/enhancement_template.md -**Right:** Create `workflows/index.md` that LINKS to guidelines/enhancement_template.md +**Wrong:** Verbatim-copying `guidelines/enhancement_template.md` into `workflows/enhancement-process.md` +**Right:** Create `workflows/enhancement-process.md` as an AI-optimized reformatted guide (prose β†’ tables/checklists/YAML), and link the authoritative source from `workflows/index.md` ### ❌ Mistake 4: Including Component-Specific Content **Wrong:** Creating files for component-specific internals @@ -536,7 +538,7 @@ Phase 9: Report ```bash /platform-docs [--path ] -``` +```text **Arguments:** - `--path `: Path to target repository (default: current directory) @@ -579,7 +581,7 @@ Phase 9: Report ## Final Report Template -``` +```text βœ… AI-Optimized Documentation Created Location: ai-docs/ @@ -619,7 +621,7 @@ Next Steps: - Repository index for discovery Co-Authored-By: Claude Sonnet 4.5 " -``` +```text --- diff --git a/plugins/agentic-docs/skills/platform/scripts/discover.sh b/plugins/agentic-docs/skills/platform/scripts/discover.sh index 3297def3d..d6ca8a450 100755 --- a/plugins/agentic-docs/skills/platform/scripts/discover.sh +++ b/plugins/agentic-docs/skills/platform/scripts/discover.sh @@ -26,7 +26,7 @@ if [ -d "$REPO_PATH/ai-docs" ]; then # Count existing files echo "" echo "πŸ“Š Existing files:" - for dir in platform/operator-patterns practices/testing practices/security practices/reliability practices/development domain/kubernetes domain/openshift decisions workflows references; do + 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" diff --git a/plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh b/plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh index ae31ae3e2..60a019d57 100755 --- a/plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh +++ b/plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh @@ -38,7 +38,7 @@ check_file_count() { local count=0 if [ -d "$AI_DOCS/$dir" ]; then - count=$(find "$AI_DOCS/$dir" -name "$pattern" -type f 2>/dev/null | grep -v index.md | wc -l) + count=$(find "$AI_DOCS/$dir" -name "$pattern" ! -name "index.md" -type f 2>/dev/null | wc -l) fi echo " $label: $count files (need $min_count minimum)" diff --git a/plugins/agentic-docs/skills/platform/scripts/gap-detection.sh b/plugins/agentic-docs/skills/platform/scripts/gap-detection.sh index f45796bd7..b1033a0c4 100755 --- a/plugins/agentic-docs/skills/platform/scripts/gap-detection.sh +++ b/plugins/agentic-docs/skills/platform/scripts/gap-detection.sh @@ -136,7 +136,7 @@ if [ $MISSING_COUNT -eq 0 ]; then else echo "πŸ“Š Summary: $MISSING_COUNT missing files detected" echo "" - echo "Run /update-docs to add missing content." + echo "Run /update-platform-docs to add missing content." fi exit 0 diff --git a/plugins/agentic-docs/skills/platform/scripts/validate.sh b/plugins/agentic-docs/skills/platform/scripts/validate.sh index 96f732e55..5462433a0 100755 --- a/plugins/agentic-docs/skills/platform/scripts/validate.sh +++ b/plugins/agentic-docs/skills/platform/scripts/validate.sh @@ -22,7 +22,7 @@ else echo " βœ… AGENTS.md" LINE_COUNT=$(wc -l < "$REPO_PATH/AGENTS.md") echo " $LINE_COUNT lines" - if [ "$LINE_COUNT" -lt 80 ] || [ "$LINE_COUNT" -gt 220 ]; then + if [ "$LINE_COUNT" -lt 100 ] || [ "$LINE_COUNT" -gt 200 ]; then echo " ⚠️ WARNING: Should be 100-200 lines (current: $LINE_COUNT)" fi fi diff --git a/plugins/agentic-docs/skills/platform/templates/AGENTS.md b/plugins/agentic-docs/skills/platform/templates/AGENTS.md index 6deba2525..fbe9394be 100644 --- a/plugins/agentic-docs/skills/platform/templates/AGENTS.md +++ b/plugins/agentic-docs/skills/platform/templates/AGENTS.md @@ -26,7 +26,7 @@ When working on OpenShift: ## Compressed Documentation Index -``` +```text [Repo Agentic Docs]|root:./ai-docs|XX files, XXXX lines | |CRITICAL_READS:{KNOWLEDGE_GRAPH.md,DESIGN_PHILOSOPHY.md} @@ -36,7 +36,7 @@ When working on OpenShift: |domain/kubernetes:{pod.md,node.md,...} |domain/openshift:{clusteroperator.md,machine.md,...} |decisions:{adr-0001-*.md,...} -``` +```text --- diff --git a/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md b/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md index 739716c8a..90427514e 100644 --- a/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md +++ b/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md @@ -24,7 +24,7 @@ **Core Principle**: Describe what you want, Kubernetes makes it happen. -``` +```text User declares: "I want 3 replicas" (Desired State) Kubernetes sees: "I have 1 replica" (Current State) Controller: "I'll create 2 more" (Reconciliation) diff --git a/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md b/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md index 9f669d967..23a87665c 100644 --- a/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md +++ b/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md @@ -23,13 +23,13 @@ | **Add a feature** | workflows/index.md (links to enhancement process) | practices/development/index.md (links to API conventions) | practices/testing/index.md | | **Debug an issue** | practices/reliability/index.md | platform/operator-patterns/must-gather.md | references/repo-index.md | | **Understand a concept** | DESIGN_PHILOSOPHY.md | domain/kubernetes/ or domain/openshift/ | platform/operator-patterns/ | -| **Find a component** | references/repo-index.md | Component's AGENTS.md | Component's agentic/ docs | +| **Find a component** | references/repo-index.md | Component's AGENTS.md | Component's ai-docs/ | --- ## Knowledge Map -``` +```text β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ DESIGN_PHILOSOPHY.md β”‚ β”‚ (WHY - Core principles, read this first) β”‚ @@ -63,14 +63,14 @@ β”‚ (WHERE to find) β”‚ β”‚ repo-index, glossary β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` +```text --- ## Concept Dependencies ### Operator Development Path -``` +```text DESIGN_PHILOSOPHY.md ↓ controller-runtime.md (how reconciliation works) @@ -79,11 +79,11 @@ status-conditions.md (how to report health) ↓ clusteroperator.md (how CVO sees your operator) ↓ -webhooks.md, rbac-patterns.md, finalizers.md (advanced patterns) -``` +webhooks.md, rbac.md, finalizers.md (advanced patterns) +```text ### API Development Path -``` +```text DESIGN_PHILOSOPHY.md ↓ practices/development/index.md (β†’ links to dev-guide/api-conventions.md) @@ -91,16 +91,16 @@ practices/development/index.md (β†’ links to dev-guide/api-conventions.md) domain/kubernetes/crds.md (CustomResourceDefinition basics) ↓ platform/operator-patterns/webhooks.md (validation) -``` +```text ### Testing Path -``` +```text practices/testing/index.md (β†’ links to dev-guide/test-conventions.md) ↓ Testing pyramid concept ↓ E2E framework specifics -``` +```text --- diff --git a/plugins/agentic-docs/skills/platform/templates/domain-concept-template.md b/plugins/agentic-docs/skills/platform/templates/domain-concept-template.md index 6715c83dd..4e35333ee 100644 --- a/plugins/agentic-docs/skills/platform/templates/domain-concept-template.md +++ b/plugins/agentic-docs/skills/platform/templates/domain-concept-template.md @@ -26,27 +26,27 @@ spec: 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. @@ -55,12 +55,12 @@ Brief explanation of the flow. ### Example 1: Common Use Case ```yaml # Practical example -``` +```text ### Example 2: Advanced Use Case ```yaml # Advanced example -``` +```text ## Related Concepts diff --git a/plugins/agentic-docs/skills/platform/templates/operator-pattern-template.md b/plugins/agentic-docs/skills/platform/templates/operator-pattern-template.md index 77d386b83..10eb85476 100644 --- a/plugins/agentic-docs/skills/platform/templates/operator-pattern-template.md +++ b/plugins/agentic-docs/skills/platform/templates/operator-pattern-template.md @@ -23,7 +23,7 @@ import "relevant/package" func ExampleImplementation() { // Show actual code } -``` +```text ## Best Practices @@ -36,12 +36,12 @@ func ExampleImplementation() { ### Pattern Variant 1 ```yaml # YAML or code example -``` +```text ### Pattern Variant 2 ```go // Another code example -``` +```text ## Examples in Components diff --git a/plugins/agentic-docs/skills/platform/templates/practice-template.md b/plugins/agentic-docs/skills/platform/templates/practice-template.md index 90308bc08..9354ce215 100644 --- a/plugins/agentic-docs/skills/platform/templates/practice-template.md +++ b/plugins/agentic-docs/skills/platform/templates/practice-template.md @@ -17,7 +17,7 @@ Core principle or diagram explaining the approach. ### Step 1: First Action ```bash # Commands or code -``` +```text **What to do**: Explanation **When to use**: Guidance @@ -25,7 +25,7 @@ Core principle or diagram explaining the approach. ### Step 2: Second Action ```bash # More commands -``` +```text ## Best Practices diff --git a/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md b/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md index e92d5711f..399e1f3b6 100644 --- a/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md +++ b/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md @@ -33,7 +33,7 @@ Exec-plans are **ephemeral** feature tracking documents that bridge enhancements ### Starting a New Feature ```bash -# In your component repo: component-repo/agentic/exec-plans/ +# In your component repo: component-repo/ai-docs/exec-plans/ # Copy template from Tier 1 curl -O https://raw.githubusercontent.com/openshift/enhancements/master/ai-docs/workflows/exec-plans/template.md @@ -48,7 +48,7 @@ mv template.md active/feature-name.md # - Testing Strategy: How you'll test it # - Dependencies: What you need from other teams # - Risks: What could go wrong -``` +```text ### During Implementation @@ -69,14 +69,14 @@ cat active/feature-name.md # 2. Extract to permanent docs: # If architectural decision was made: -cp agentic/decisions/adr-template.md agentic/decisions/adr-NNNN-decision-name.md +cp ai-docs/decisions/adr-template.md ai-docs/decisions/adr-NNNN-decision-name.md # Document the decision in the ADR # If architecture changed: -# Update agentic/architecture/components.md with new structure +# Update ai-docs/architecture/components.md with new structure # If new CRD was added: -# Already documented in agentic/domain/crd-name.md +# Already documented in ai-docs/domain/crd-name.md # 3. Delete the exec-plan (it's in git history if needed) git rm active/feature-name.md @@ -85,11 +85,11 @@ git commit -m "Complete feature-name implementation Architectural decisions documented in adr-NNNN-*.md Architecture changes in architecture/components.md " -``` +```text **Why delete?** - Exec-plans are ephemeral tracking, not permanent docs -- Git history preserves it if needed: `git log --all -- agentic/exec-plans/active/feature-name.md` +- Git history preserves it if needed: `git log --all -- ai-docs/exec-plans/active/feature-name.md` - Permanent knowledge belongs in ADRs and architecture docs ## Relationship to Other Docs @@ -101,7 +101,7 @@ Architecture changes in architecture/components.md - Scope: Platform-wide, cross-repo **Exec-Plan (Tier 2)**: -- Where: Component repository (`agentic/exec-plans/active/`) +- Where: Component repository (`ai-docs/exec-plans/active/`) - What: Implementation tracking, PR coordination, decisions - When: During implementation - Scope: Component-specific @@ -119,10 +119,10 @@ When feature is complete, ask: | Question | Yes | Action | |----------|-----|--------| -| Did we make an architectural decision? | βœ… | Create ADR in `agentic/decisions/adr-NNNN-*.md` | -| Did component architecture change? | βœ… | Update `agentic/architecture/components.md` | -| Did we add a new CRD? | βœ… | Already in `agentic/domain/*.md` | -| Did we add new components/controllers? | βœ… | Update `agentic/architecture/components.md` | +| Did we make an architectural decision? | βœ… | Create ADR in `ai-docs/decisions/adr-NNNN-*.md` | +| Did component architecture change? | βœ… | Update `ai-docs/architecture/components.md` | +| Did we add a new CRD? | βœ… | Already in `ai-docs/domain/*.md` | +| Did we add new components/controllers? | βœ… | Update `ai-docs/architecture/components.md` | | Just implementation (no architecture)? | βœ… | Delete exec-plan (it's in git history) | **Then**: Delete the exec-plan. It's ephemeral tracking, not permanent documentation. @@ -133,7 +133,7 @@ When feature is complete, ask: 1. **New Enhancement Approved** - Enhancement: "Add support for custom kernels" - - Create: `agentic/exec-plans/active/custom-kernels.md` + - Create: `ai-docs/exec-plans/active/custom-kernels.md` 2. **During Development** (Week 1-4) - Update exec-plan with PRs @@ -145,19 +145,19 @@ When feature is complete, ask: **Extract permanent knowledge**: ```bash # Architectural decision made during development - vim agentic/decisions/adr-0004-kernel-args-vs-modules.md + vim ai-docs/decisions/adr-0004-kernel-args-vs-modules.md # Document: Why kernel args? Performance, compatibility, rollback # Architecture changed (new controller added) - vim agentic/architecture/components.md + vim ai-docs/architecture/components.md # Add: KernelController - manages kernel arguments via MachineConfig # New CRD added - vim agentic/domain/kernelconfig.md + vim ai-docs/domain/kernelconfig.md # Already documented during development # Delete ephemeral exec-plan - git rm agentic/exec-plans/active/custom-kernels.md + git rm ai-docs/exec-plans/active/custom-kernels.md git commit -m "Complete custom kernels feature Architectural decision in adr-0004-kernel-args-vs-modules.md diff --git a/plugins/agentic-docs/skills/update-platform-docs/SKILL.md b/plugins/agentic-docs/skills/update-platform-docs/SKILL.md index 4a9cab532..899e5f9f9 100644 --- a/plugins/agentic-docs/skills/update-platform-docs/SKILL.md +++ b/plugins/agentic-docs/skills/update-platform-docs/SKILL.md @@ -74,7 +74,7 @@ Based on user request, perform ONE OR MORE of: #### Update AGENTS.md - [ ] Read current `AGENTS.md` - [ ] Add new navigation links -- [ ] Verify line count stays ≀200 lines +- [ ] Verify line count stays 100-200 lines - [ ] Maintain compressed table format #### Update Existing Files @@ -86,7 +86,7 @@ Based on user request, perform ONE OR MORE of: ### Phase 3: Validation - [ ] Run validation: `bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH"` - [ ] Verify new files follow conventions -- [ ] Verify AGENTS.md ≀200 lines +- [ ] Verify AGENTS.md 100-200 lines - [ ] Verify internal links work ### Phase 4: Report @@ -117,8 +117,7 @@ Based on user request, perform ONE OR MORE of: 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. Update structure in platform/scripts/create-structure.sh -7. Validate +6. Validate ### Scenario 3: Update AGENTS.md @@ -146,7 +145,7 @@ Based on user request, perform ONE OR MORE of: **MUST follow these conventions:** -1. **Index files**: Use `index.md` NOT `README.md` +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 @@ -182,7 +181,7 @@ After updates, verify: βœ… New files use correct naming conventions βœ… Index files updated with new entries -βœ… AGENTS.md updated if needed (and ≀200 lines) +βœ… 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 @@ -311,7 +310,7 @@ mkdir -p ai-docs/workflows/exec-plans ## Success Output -``` +```text βœ… Platform Documentation Updated Repository: /path/to/enhancements @@ -321,7 +320,6 @@ Changes: βœ… Created: ai-docs/workflows/exec-plans/template.md βœ… Updated: ai-docs/workflows/index.md βœ… Updated: AGENTS.md (added exec-plans link) - βœ… Updated: skills/platform/scripts/create-structure.sh Validation: βœ… File naming conventions correct @@ -351,8 +349,8 @@ Next Steps: **Right:** Always update corresponding index.md ### ❌ Mistake 4: Inconsistent Naming -**Wrong:** Creating `README.md` or `adr-1-topic.md` -**Right:** Use `index.md` and `adr-0001-topic.md` +**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 5: Duplicating Content **Wrong:** Copying content from dev-guide/guidelines @@ -361,5 +359,5 @@ Next Steps: ## See Also - `/platform-docs` - Create platform documentation from scratch -- [Platform SKILL.md](../SKILL.md) - Full platform docs creation guide -- [Validation Script](../scripts/validate.sh) - Structure validation +- [Platform SKILL.md](../platform/SKILL.md) - Full platform docs creation guide +- [Validation Script](../platform/scripts/validate.sh) - Structure validation From bbb32c3bb5f77a3558bb75be0fb64607f131e70d Mon Sep 17 00:00:00 2001 From: Prashanth684 Date: Thu, 14 May 2026 10:14:42 -0700 Subject: [PATCH 3/3] Refactor agentic-docs plugin: remove platform-docs skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Platform documentation in openshift/enhancements/ai-docs/ already exists and was created using this skill. Remove the /platform-docs skill that was designed to create it from scratch - it's no longer needed. Changes: - Remove entire skills/platform/ directory - Keep /update-platform-docs for incremental updates to existing platform docs - Keep /component-docs for creating component-level documentation - Update README to clarify platform docs "already exist" - Simplify tier architecture description (tier-1/tier-2 β†’ platform/component) - Update component skill templates to reference "platform docs" consistently - Update validation scripts to remove platform-specific checks - Remove platform-docs from marketplace registration This simplifies the plugin to focus on its two active use cases: 1. Creating new component documentation (/component-docs) 2. Updating existing platform documentation (/update-platform-docs) --- docs/data.json | 11 +- plugins/agentic-docs/OWNERS | 10 + plugins/agentic-docs/README.md | 26 +- .../{component => component-docs}/SKILL.md | 122 ++-- .../scripts/create-structure.sh | 0 .../scripts/validate.sh | 18 +- .../templates/AGENTS-template.md | 13 +- .../templates/DEVELOPMENT-template.md | 8 +- .../templates/TESTING-template.md | 8 +- .../templates/adr-template.md | 4 +- .../templates/domain-concept-template.md | 4 +- .../templates/ecosystem-template.md | 20 +- .../templates/exec-plans-README-template.md | 6 +- plugins/agentic-docs/skills/platform/SKILL.md | 628 ------------------ .../platform/scripts/create-structure.sh | 32 - .../skills/platform/scripts/discover.sh | 46 -- .../skills/platform/scripts/fill-gaps.sh | 96 --- .../skills/platform/scripts/gap-detection.sh | 142 ---- .../platform/scripts/populate-templates.sh | 28 - .../skills/platform/scripts/validate.sh | 152 ----- .../skills/platform/templates/AGENTS.md | 63 -- .../platform/templates/DESIGN_PHILOSOPHY.md | 121 ---- .../platform/templates/KNOWLEDGE_GRAPH.md | 136 ---- .../templates/workflows/exec-plan-template.md | 74 --- .../templates/workflows/exec-plans-README.md | 188 ------ .../skills/update-platform-docs/SKILL.md | 32 +- .../update-platform-docs/scripts/discover.sh | 47 +- .../scripts/gap-detection.sh | 143 +++- .../update-platform-docs/scripts/validate.sh | 153 ++++- .../skills/update-platform-docs/templates | 1 - .../templates/adr-template.md | 0 .../templates/domain-concept-template.md | 0 .../templates/operator-pattern-template.md | 0 .../templates/practice-template.md | 0 34 files changed, 470 insertions(+), 1862 deletions(-) create mode 100644 plugins/agentic-docs/OWNERS rename plugins/agentic-docs/skills/{component => component-docs}/SKILL.md (79%) rename plugins/agentic-docs/skills/{component => component-docs}/scripts/create-structure.sh (100%) rename plugins/agentic-docs/skills/{component => component-docs}/scripts/validate.sh (95%) rename plugins/agentic-docs/skills/{component => component-docs}/templates/AGENTS-template.md (65%) rename plugins/agentic-docs/skills/{component => component-docs}/templates/DEVELOPMENT-template.md (85%) rename plugins/agentic-docs/skills/{component => component-docs}/templates/TESTING-template.md (89%) rename plugins/agentic-docs/skills/{component => component-docs}/templates/adr-template.md (80%) rename plugins/agentic-docs/skills/{component => component-docs}/templates/domain-concept-template.md (81%) rename plugins/agentic-docs/skills/{component => component-docs}/templates/ecosystem-template.md (61%) rename plugins/agentic-docs/skills/{component => component-docs}/templates/exec-plans-README-template.md (63%) delete mode 100644 plugins/agentic-docs/skills/platform/SKILL.md delete mode 100755 plugins/agentic-docs/skills/platform/scripts/create-structure.sh delete mode 100755 plugins/agentic-docs/skills/platform/scripts/discover.sh delete mode 100755 plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh delete mode 100755 plugins/agentic-docs/skills/platform/scripts/gap-detection.sh delete mode 100755 plugins/agentic-docs/skills/platform/scripts/populate-templates.sh delete mode 100755 plugins/agentic-docs/skills/platform/scripts/validate.sh delete mode 100644 plugins/agentic-docs/skills/platform/templates/AGENTS.md delete mode 100644 plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md delete mode 100644 plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md delete mode 100644 plugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.md delete mode 100644 plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md mode change 120000 => 100755 plugins/agentic-docs/skills/update-platform-docs/scripts/discover.sh mode change 120000 => 100755 plugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.sh mode change 120000 => 100755 plugins/agentic-docs/skills/update-platform-docs/scripts/validate.sh delete mode 120000 plugins/agentic-docs/skills/update-platform-docs/templates rename plugins/agentic-docs/skills/{platform => update-platform-docs}/templates/adr-template.md (100%) rename plugins/agentic-docs/skills/{platform => update-platform-docs}/templates/domain-concept-template.md (100%) rename plugins/agentic-docs/skills/{platform => update-platform-docs}/templates/operator-pattern-template.md (100%) rename plugins/agentic-docs/skills/{platform => update-platform-docs}/templates/practice-template.md (100%) diff --git a/docs/data.json b/docs/data.json index 04e62c417..8ff350327 100644 --- a/docs/data.json +++ b/docs/data.json @@ -1831,15 +1831,10 @@ "name": "agentic-docs", "skills": [ { - "description": "Create lean tier-2 component documentation for OpenShift repositories", - "id": "component", + "description": "Create lean component documentation for OpenShift repositories", + "id": "component-docs", "name": "component-docs" }, - { - "description": "Create AI-optimized platform documentation for openshift/enhancements", - "id": "platform", - "name": "platform-docs" - }, { "description": "Update existing platform documentation with automatic gap detection in openshift/enhancements", "id": "update-platform-docs", @@ -1849,4 +1844,4 @@ "version": "1.0.0" } ] -} +} \ No newline at end of file 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 index 94608c536..961c070db 100644 --- a/plugins/agentic-docs/README.md +++ b/plugins/agentic-docs/README.md @@ -4,46 +4,36 @@ AI-optimized OpenShift documentation with progressive disclosure, reference styl ## Two-Tier Architecture -**Tier 1: Platform Hub** (`openshift/enhancements/ai-docs/`) +**Platform Docs** (`openshift/enhancements/ai-docs/`) - **Already exists** Generic patterns, testing, security, K8s/OpenShift fundamentals, cross-repo ADRs. ~34 files, 4.4k lines. -**Tier 2: Component Repos** (`{component}/ai-docs/`) -Component CRDs, architecture, local ADRs, exec-plans. Links to Tier 1. ~15 files, 2.5k lines (58% leaner). +**Component Docs** (`{component}/ai-docs/`) +Component CRDs, architecture, local ADRs, exec-plans. Links to platform docs. ~15 files, 2.5k lines (58% leaner). ## Skills -### `/platform-docs` -Creates Tier 1 platform documentation in `openshift/enhancements/ai-docs/`. - -```bash -cd /path/to/openshift/enhancements -/platform-docs -``` - -Creates AGENTS.md (navigation) + ai-docs/ with: platform patterns (controller-runtime, webhooks, finalizers, RBAC, must-gather), domain concepts (K8s/OpenShift APIs), practices (testing, security, reliability), cross-repo ADRs, workflows (exec-plans, enhancement process), and references (repo-index, glossary, API pointers). - ### `/update-platform-docs` -Incrementally update Tier 1 docs with automatic gap detection. +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 when ai-docs/ exists (otherwise use `/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 Tier 2 lean docs in component repositories. +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 Tier 1, development/testing guides. Excludes generic patterns (lives in Tier 1). Example: [machine-config-operator/ai-docs](https://github.com/openshift/machine-config-operator/tree/master/ai-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/{platform,update-platform-docs,component}/` with SKILL.md, scripts, and templates. +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/SKILL.md b/plugins/agentic-docs/skills/component-docs/SKILL.md similarity index 79% rename from plugins/agentic-docs/skills/component/SKILL.md rename to plugins/agentic-docs/skills/component-docs/SKILL.md index ed5c86aee..71b73fddb 100644 --- a/plugins/agentic-docs/skills/component/SKILL.md +++ b/plugins/agentic-docs/skills/component-docs/SKILL.md @@ -1,27 +1,27 @@ --- name: component-docs -description: Create lean tier-2 component documentation for OpenShift repositories +description: Create lean component documentation for OpenShift repositories trigger: explicit model: sonnet --- # Component Documentation Creator -Creates lean tier-2 agentic documentation for OpenShift component repositories. +Creates lean component agentic documentation for OpenShift component repositories. -**Philosophy**: Component docs contain ONLY component-specific knowledge. Generic platform patterns live in tier-1 (openshift/enhancements/ai-docs/). +**Philosophy**: Component docs contain ONLY component-specific knowledge. Generic platform patterns live in platform (openshift/enhancements/ai-docs/). ## Two-Tier Architecture -### Tier 1: Platform Hub (openshift/enhancements/ai-docs/) +### Platform: Platform Hub (openshift/enhancements/ai-docs/) **Contains**: Operator patterns, testing practices, security guidelines, Kubernetes/OpenShift fundamentals, cross-repo ADRs -### Tier 2: Component Repos (LEAN) +### Component: Component Repos (LEAN) **Contains**: Component-specific CRDs, component architecture, component ADRs, exec-plans **Decision Rule**: "Would another repo need to duplicate this?" -- YES β†’ Tier 1 (platform) -- NO β†’ Tier 2 (component) +- YES β†’ Platform (platform) +- NO β†’ Component (component) ## What Gets Created @@ -37,14 +37,14 @@ component-repo/ β”‚ └── adr-template.md β”œβ”€β”€ exec-plans/ β”‚ β”œβ”€β”€ active/ # Features being implemented - β”‚ └── README.md # Pointer to Tier 1 guidance + β”‚ └── README.md # Pointer to Platform guidance β”œβ”€β”€ references/ - β”‚ └── ecosystem.md # Links to Tier 1 (CRITICAL) + β”‚ └── ecosystem.md # Links to Platform (CRITICAL) β”œβ”€β”€ [COMPONENT]_DEVELOPMENT.md └── [COMPONENT]_TESTING.md ```text -## What NOT to Include (lives in Tier 1) +## What NOT to Include (lives in Platform) ❌ Generic operator patterns (controller-runtime, status conditions) ❌ Testing practices (test pyramid, E2E framework) @@ -56,7 +56,7 @@ component-repo/ ## Execution Workflow ### Phase 1: Setup -- [ ] Find skill directory: `SKILL_DIR=$(find ~/.claude/plugins/cache -path "*/component" -type d | head -1)` +- [ ] 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"` @@ -65,7 +65,7 @@ component-repo/ - [ ] Create master entry point at repo root - [ ] Include compressed index of component docs - [ ] Add retrieval-first instruction -- [ ] Add Tier 1 ecosystem hub links +- [ ] Add Platform ecosystem hub links - [ ] Add component quick navigation - [ ] Validate line count: `wc -l AGENTS.md` (target: 80-100) @@ -74,7 +74,7 @@ component-repo/ - [ ] 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 Tier 1 for generic patterns +- [ ] Focus on component-specific behavior, link to Platform for generic patterns ### Phase 4: Component Architecture - [ ] Create architecture/components.md @@ -86,26 +86,26 @@ component-repo/ - [ ] 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 Tier 1) +- [ ] 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 Tier 1 guidance -- [ ] Link to Tier 1: `https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/` -- [ ] NO templates or detailed guidance (lives in Tier 1) +- [ ] 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 Tier 1 operator patterns -- [ ] Link to Tier 1 testing practices -- [ ] Link to Tier 1 security practices -- [ ] Link to Tier 1 Kubernetes/OpenShift fundamentals -- [ ] Link to Tier 1 cross-repo ADRs +- [ ] 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 Tier 1 for generic practices +- [ ] Link to Platform for generic practices - [ ] Document ONLY component-specific details: - Build instructions (make targets, go commands) - Repository structure (cmd/, pkg/ organization) @@ -118,7 +118,7 @@ component-repo/ - [ ] 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 Tier 1 links +- [ ] 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 @@ -126,7 +126,7 @@ component-repo/ **Link Validation**: - Automatically checks all HTTP/HTTPS links (with timeout and user agent) - Validates internal/relative links (file existence) -- Flags known Tier 1 planned links as "KNOWN BROKEN" +- 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 @@ -135,13 +135,13 @@ component-repo/ **Length**: 80-100 lines (strict limit) **Required Sections**: -1. Component metadata (name, repository, tier) -2. Tier 1 reference (link to ecosystem hub) +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. Tier 1 ecosystem links (operator patterns, testing, security, etc.) +7. Platform ecosystem links (operator patterns, testing, security, etc.) **Format**: Compressed, table-based, links not prose @@ -151,9 +151,8 @@ component-repo/ **Component**: Machine Config Operator **Repository**: openshift/machine-config-operator -**Documentation Tier**: 2 (Component-specific) -> **Generic Platform Patterns**: See [Tier 1 Hub](https://github.com/openshift/enhancements/tree/master/ai-docs) +> **Generic Platform Patterns**: See Platform documentation (openshift/enhancements/ai-docs/) ## What is MCO? @@ -173,9 +172,9 @@ ai-docs/ └── exec-plans/ # Feature planning ```text -## Tier 1 Links +## Platform Links -**Patterns**: [Operator](tier1-link) | [Testing](tier1-link) | [Security](tier1-link) +**Patterns**: Operator | Testing | Security (see Platform docs) ## Component-Specific Domain Concepts @@ -215,7 +214,7 @@ ai-docs/ **Example Component ADRs**: - Why rpm-ostree for OS updates (MCO) - Why Ignition format for config (MCO) -- Why etcd for platform state (Tier 1, NOT component) +- Why etcd for platform state (Platform, NOT component) **Template**: `decisions/adr-template.md` @@ -225,8 +224,8 @@ ai-docs/ **Location**: Component repo (`ai-docs/exec-plans/active/`) -**Guidance**: Lives in Tier 1 (platform-docs) -- **Templates & Usage**: See [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/) +**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` @@ -234,25 +233,25 @@ ai-docs/ ```text ai-docs/exec-plans/ β”œβ”€β”€ active/ # Component-specific exec-plans go here -└── README.md # Pointer to Tier 1 guidance +└── README.md # Pointer to Platform guidance ```text **What component-docs creates**: - `active/` directory (empty, ready for exec-plans) -- `README.md` with pointer to Tier 1 +- `README.md` with pointer to Platform **What component-docs does NOT create**: -- ❌ Templates (live in Tier 1) -- ❌ Detailed guidance (lives in Tier 1) +- ❌ Templates (live in Platform) +- ❌ Detailed guidance (lives in Platform) - ❌ `completed/` directory (exec-plans are deleted after extracting knowledge) -**Workflow**: See [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/README.md) +**Workflow**: See Platform exec-plans guidance ## Ecosystem References **File**: `references/ecosystem.md` -**Links to Tier 1**: +**Links to Platform**: - Operator patterns (controller-runtime, status conditions, webhooks, finalizers, RBAC) - Testing practices (pyramid, E2E framework) - Security practices (STRIDE, RBAC, secrets) @@ -261,7 +260,7 @@ ai-docs/exec-plans/ - OpenShift fundamentals (ClusterOperator, release image) - Cross-repo ADRs (etcd, CVO orchestration, immutable nodes) -**Purpose**: Single source of truth for Tier 1 links +**Purpose**: Single source of truth for Platform links ## Development & Testing Docs @@ -305,7 +304,7 @@ ai-docs/exec-plans/ - Environment variables - Local development quirks -**Link to Tier 1 for**: Generic Go standards, controller-runtime patterns, CI/CD workflows +**Link to Platform for**: Generic Go standards, controller-runtime patterns, CI/CD workflows ### TESTING.md Contents @@ -347,7 +346,7 @@ ai-docs/exec-plans/ - Known flaky tests - Test environment requirements -**Link to Tier 1 for**: Test pyramid philosophy (60/30/10), E2E framework patterns, mock vs real strategies +**Link to Platform for**: Test pyramid philosophy (60/30/10), E2E framework patterns, mock vs real strategies ### Example from MCO @@ -372,7 +371,7 @@ ai-docs/exec-plans/ - 80-100 lines - Compressed index format - Retrieval-first instruction -- Tier 1 ecosystem links section +- Platform ecosystem links section βœ… **No duplication**: - No testing pyramid explanations @@ -383,9 +382,9 @@ ai-docs/exec-plans/ βœ… **Ecosystem references**: - references/ecosystem.md exists -- Links to Tier 1 operator patterns -- Links to Tier 1 testing practices -- Links to Tier 1 security practices +- Links to Platform operator patterns +- Links to Platform testing practices +- Links to Platform security practices βœ… **Component-specific only**: - Domain concepts are component CRDs @@ -395,12 +394,12 @@ ai-docs/exec-plans/ βœ… **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 Tier 1 planned links +- No broken links except known Platform planned links - Links to upstream documentation are valid and current ## Anti-Patterns -### ❌ DON'T duplicate Tier 1 content +### ❌ DON'T duplicate Platform content **Wrong**: ```markdown @@ -417,7 +416,7 @@ ai-docs/exec-plans/ ```markdown # COMPONENT_TESTING.md (90 lines, 100% component-specific) -> Testing practices: See [Tier 1](tier1-link) +> Testing practices: See Platform docs ## Component Test Suites [90 lines component-specific] @@ -426,12 +425,12 @@ ai-docs/exec-plans/ ### ❌ DON'T explain generic patterns **Wrong**: Explaining controller-runtime in component docs -**Right**: Link to Tier 1, document component-specific usage +**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 Tier 1 +**Right**: ADR about etcd in Platform ## Metrics @@ -443,16 +442,15 @@ ai-docs/exec-plans/ **Benefits**: - 58% smaller than single-tier - Zero duplication across ecosystem -- Pattern updates: 1 Tier 1 PR (not 60+ component PRs) +- Pattern updates: 1 Platform PR (not 60+ component PRs) ## Prerequisites **Before running**: -1. βœ… Tier 1 exists at openshift/enhancements/ai-docs/ +1. βœ… Platform exists at openshift/enhancements/ai-docs/ 2. βœ… Repository is OpenShift component 3. βœ… You understand two-tier architecture - -**If Tier 1 doesn't exist**: Create it first using `/platform-docs` +4. βœ… Platform documentation exists at openshift/enhancements/ai-docs/ ## Arguments @@ -478,17 +476,17 @@ Structure: βœ… Architecture: 1 file (components.md) βœ… Component ADRs: 3 files βœ… Exec-plans: README.md, active/ - βœ… Ecosystem references: ecosystem.md with Tier 1 links + βœ… 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 - βœ… Tier 1 links present + βœ… Platform links present βœ… Component-specific content only -Tier 1 Links: +Platform Links: - Ecosystem hub: openshift/enhancements/ai-docs - Operator patterns: 6 links - Testing practices: 3 links @@ -523,6 +521,6 @@ Next Steps: ## See Also -- `/platform-docs` - Create Tier 1 platform documentation -- [Tier 1 Hub](https://github.com/openshift/enhancements/tree/master/ai-docs) +- `/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/scripts/create-structure.sh b/plugins/agentic-docs/skills/component-docs/scripts/create-structure.sh similarity index 100% rename from plugins/agentic-docs/skills/component/scripts/create-structure.sh rename to plugins/agentic-docs/skills/component-docs/scripts/create-structure.sh diff --git a/plugins/agentic-docs/skills/component/scripts/validate.sh b/plugins/agentic-docs/skills/component-docs/scripts/validate.sh similarity index 95% rename from plugins/agentic-docs/skills/component/scripts/validate.sh rename to plugins/agentic-docs/skills/component-docs/scripts/validate.sh index 373825f02..549124704 100755 --- a/plugins/agentic-docs/skills/component/scripts/validate.sh +++ b/plugins/agentic-docs/skills/component-docs/scripts/validate.sh @@ -2,7 +2,7 @@ # # Component Documentation Validator # -# Validates component-tier documentation structure and links. +# Validates component-level documentation structure and links. # # Usage: # ./validate.sh [REPO_PATH] [VALIDATE_LINKS] @@ -234,11 +234,11 @@ else echo " $LINE_COUNT lines (target: 80-100) βœ…" fi -# Check for Tier 1 references -if grep -q "Tier 1" "$REPO_PATH/AGENTS.md" || grep -q "openshift/enhancements" "$REPO_PATH/AGENTS.md"; then - echo " βœ… Tier 1 ecosystem references found" +# 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 Tier 1 ecosystem references found" + echo " ⚠️ No Platform ecosystem references found" fi # Check for retrieval-first instruction @@ -264,10 +264,10 @@ echo "" # Check ecosystem.md if [ -f "$REPO_PATH/ai-docs/references/ecosystem.md" ]; then echo " βœ… references/ecosystem.md exists" - if grep -q "Tier 1" "$REPO_PATH/ai-docs/references/ecosystem.md"; then - echo " Contains Tier 1 links βœ…" + if grep -q "Platform" "$REPO_PATH/ai-docs/references/ecosystem.md"; then + echo " Contains Platform links βœ…" else - echo " ⚠️ No Tier 1 links found" + echo " ⚠️ No Platform links found" fi else echo " ⚠️ references/ecosystem.md missing" @@ -289,7 +289,7 @@ FORBIDDEN_PATTERNS=( 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 Tier 1)" + echo " ⚠️ Found generic pattern: '$pattern' (should link to Platform)" FOUND_DUPLICATION=true fi done diff --git a/plugins/agentic-docs/skills/component/templates/AGENTS-template.md b/plugins/agentic-docs/skills/component-docs/templates/AGENTS-template.md similarity index 65% rename from plugins/agentic-docs/skills/component/templates/AGENTS-template.md rename to plugins/agentic-docs/skills/component-docs/templates/AGENTS-template.md index e34dbe5c4..a1e328964 100644 --- a/plugins/agentic-docs/skills/component/templates/AGENTS-template.md +++ b/plugins/agentic-docs/skills/component-docs/templates/AGENTS-template.md @@ -2,9 +2,8 @@ **Component**: [Component Full Name] **Repository**: openshift/[repo-name] -**Documentation Tier**: 2 (Component-specific) -> **Generic Platform Patterns**: See [Tier 1 Ecosystem Hub](https://github.com/openshift/enhancements/tree/master/ai-docs) for operator patterns, testing practices, security guidelines, and cross-repo ADRs. +> **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]? @@ -27,14 +26,14 @@ ai-docs/ β”œβ”€β”€ decisions/ # Component-specific ADRs β”œβ”€β”€ exec-plans/ # Feature planning β”œβ”€β”€ references/ -β”‚ └── ecosystem.md # Links to Tier 1 +β”‚ └── 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 [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans). +**Exec-Plans**: Use `active/` for new features. See [Platform Exec-Plans Guide](Platform documentation). -**Platform Patterns (Tier 1)**: [Operator](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns) | [Testing](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) | [Security](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/security) +**Platform Patterns (Platform)**: [Operator](Platform documentation) | [Testing](Platform documentation) | [Security](Platform documentation) ## Knowledge Graph @@ -49,7 +48,7 @@ ai-docs/ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ [references/ecosystem] - Links to Tier 1 + Links to Platform ```text **AI Agent Path**: domain/ β†’ architecture/ β†’ decisions/ β†’ [COMPONENT]_DEVELOPMENT.md @@ -60,4 +59,4 @@ ai-docs/ --- -**Tier 1 Hub**: https://github.com/openshift/enhancements/tree/master/ai-docs +**Platform Documentation**: openshift/enhancements/ai-docs/ diff --git a/plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md b/plugins/agentic-docs/skills/component-docs/templates/DEVELOPMENT-template.md similarity index 85% rename from plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md rename to plugins/agentic-docs/skills/component-docs/templates/DEVELOPMENT-template.md index 71f22187f..3077eb84c 100644 --- a/plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md +++ b/plugins/agentic-docs/skills/component-docs/templates/DEVELOPMENT-template.md @@ -1,6 +1,6 @@ # [Component Name] - Development Guide -> **Generic Development Practices**: See [Tier 1 Development Practices](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/development) for Go standards, controller-runtime patterns, and CI/CD workflows. +> **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. @@ -127,7 +127,7 @@ Location: `pkg/controller/[name]/` - `reconcile.go` - Reconcile logic - `*_test.go` - Unit tests -**Generic controller patterns**: See [Tier 1](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns/controller-runtime.md) +**Generic controller patterns**: See [Platform](Platform documentation) ### Domain Logic @@ -181,7 +181,7 @@ 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 [Tier 1 Release Process](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/development). +Component is released as part of OpenShift release image. See [Platform Release Process](Platform documentation). ## Component-Specific Notes @@ -196,4 +196,4 @@ Component is released as part of OpenShift release image. See [Tier 1 Release Pr - [Testing Guide](./[COMPONENT]_TESTING.md) - [Architecture](./architecture/components.md) -- [Tier 1 Development Practices](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/development) +- [Platform Development Practices](Platform documentation) diff --git a/plugins/agentic-docs/skills/component/templates/TESTING-template.md b/plugins/agentic-docs/skills/component-docs/templates/TESTING-template.md similarity index 89% rename from plugins/agentic-docs/skills/component/templates/TESTING-template.md rename to plugins/agentic-docs/skills/component-docs/templates/TESTING-template.md index d059ab25b..f91ad2169 100644 --- a/plugins/agentic-docs/skills/component/templates/TESTING-template.md +++ b/plugins/agentic-docs/skills/component-docs/templates/TESTING-template.md @@ -1,6 +1,6 @@ # [Component Name] - Testing Guide -> **Generic Testing Practices**: See [Tier 1 Testing Practices](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) for test pyramid philosophy (60/30/10), E2E framework patterns, and mock vs real strategies. +> **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. @@ -68,7 +68,7 @@ func TestReconcile(t *testing.T) { } ```text -**For generic controller patterns**, see [Tier 1 Controller Runtime](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns/controller-runtime.md) +**For generic controller patterns**, see [Platform Controller Runtime](Platform documentation) #### Domain Logic Tests @@ -207,7 +207,7 @@ func TestFeatureE2E(t *testing.T) { } ```text -**For generic E2E patterns**, see [Tier 1 E2E Framework](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) +**For generic E2E patterns**, see [Platform E2E Framework](Platform documentation) ### Component-Specific E2E Scenarios @@ -294,4 +294,4 @@ Example: - [Development Guide](./[COMPONENT]_DEVELOPMENT.md) - [Architecture](./architecture/components.md) -- [Tier 1 Testing Practices](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) +- [Platform Testing Practices](Platform documentation) diff --git a/plugins/agentic-docs/skills/component/templates/adr-template.md b/plugins/agentic-docs/skills/component-docs/templates/adr-template.md similarity index 80% rename from plugins/agentic-docs/skills/component/templates/adr-template.md rename to plugins/agentic-docs/skills/component-docs/templates/adr-template.md index 35fefc8e7..ce1338d2d 100644 --- a/plugins/agentic-docs/skills/component/templates/adr-template.md +++ b/plugins/agentic-docs/skills/component-docs/templates/adr-template.md @@ -9,7 +9,7 @@ What is the component-specific issue or situation we're addressing? -**Scope**: This ADR is component-specific. For cross-repo decisions, see [Tier 1 ADRs](https://github.com/openshift/enhancements/tree/master/ai-docs/decisions). +**Scope**: This ADR is component-specific. For cross-repo decisions, see [Platform ADRs](Platform documentation). ## Decision @@ -47,4 +47,4 @@ Why did we choose this approach for this component? - Related component docs - Related ADRs - External sources -- [Tier 1 ADRs](https://github.com/openshift/enhancements/tree/master/ai-docs/decisions) for cross-repo decisions +- [Platform ADRs](Platform documentation) for cross-repo decisions diff --git a/plugins/agentic-docs/skills/component/templates/domain-concept-template.md b/plugins/agentic-docs/skills/component-docs/templates/domain-concept-template.md similarity index 81% rename from plugins/agentic-docs/skills/component/templates/domain-concept-template.md rename to plugins/agentic-docs/skills/component-docs/templates/domain-concept-template.md index c537d733f..11c3f33f7 100644 --- a/plugins/agentic-docs/skills/component/templates/domain-concept-template.md +++ b/plugins/agentic-docs/skills/component-docs/templates/domain-concept-template.md @@ -55,8 +55,8 @@ spec: [Document ONLY component-specific behavior, not generic patterns] **For generic patterns**, see: -- Controller patterns: [Tier 1](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns) -- Status conditions: [Tier 1](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/operator-patterns/status-conditions.md) +- Controller patterns: [Platform](Platform documentation) +- Status conditions: [Platform](Platform documentation) ## Related Concepts diff --git a/plugins/agentic-docs/skills/component/templates/ecosystem-template.md b/plugins/agentic-docs/skills/component-docs/templates/ecosystem-template.md similarity index 61% rename from plugins/agentic-docs/skills/component/templates/ecosystem-template.md rename to plugins/agentic-docs/skills/component-docs/templates/ecosystem-template.md index ca1e67d44..b52ddbe30 100644 --- a/plugins/agentic-docs/skills/component/templates/ecosystem-template.md +++ b/plugins/agentic-docs/skills/component-docs/templates/ecosystem-template.md @@ -1,10 +1,10 @@ -# Tier 1 Ecosystem References +# Platform Ecosystem References -This document links to generic OpenShift/Kubernetes patterns in the Tier 1 ecosystem hub. The component inherits these platform-wide patterns and practices. +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/](https://github.com/openshift/enhancements/tree/master/ai-docs/platform/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 @@ -17,7 +17,7 @@ This document links to generic OpenShift/Kubernetes patterns in the Tier 1 ecosy ## Testing Practices -**Location**: [ai-docs/practices/testing/](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/testing) +**Location**: [ai-docs/practices/testing/](Platform documentation) - **Test Pyramid**: Unit > Integration > E2E ratio (60/30/10) - **E2E Framework**: OpenShift E2E test patterns @@ -27,7 +27,7 @@ This document links to generic OpenShift/Kubernetes patterns in the Tier 1 ecosy ## Security Practices -**Location**: [ai-docs/practices/security/](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/security) +**Location**: [ai-docs/practices/security/](Platform documentation) - **STRIDE Threat Model**: Threat modeling framework - **RBAC Guidelines**: Role and ClusterRole design @@ -37,7 +37,7 @@ This document links to generic OpenShift/Kubernetes patterns in the Tier 1 ecosy ## Reliability Practices -**Location**: [ai-docs/practices/reliability/](https://github.com/openshift/enhancements/tree/master/ai-docs/practices/reliability) +**Location**: [ai-docs/practices/reliability/](Platform documentation) - **SLO Framework**: Service Level Objectives and error budgets - **Observability**: Metrics, logging, tracing patterns @@ -47,7 +47,7 @@ This document links to generic OpenShift/Kubernetes patterns in the Tier 1 ecosy ## Kubernetes Fundamentals -**Location**: [ai-docs/domain/kubernetes/](https://github.com/openshift/enhancements/tree/master/ai-docs/domain/kubernetes) +**Location**: [ai-docs/domain/kubernetes/](Platform documentation) - **Pod**: Pod lifecycle, container specs - **CRDs**: CustomResourceDefinition patterns @@ -57,7 +57,7 @@ This document links to generic OpenShift/Kubernetes patterns in the Tier 1 ecosy ## OpenShift Fundamentals -**Location**: [ai-docs/domain/openshift/](https://github.com/openshift/enhancements/tree/master/ai-docs/domain/openshift) +**Location**: [ai-docs/domain/openshift/](Platform documentation) - **ClusterOperator**: Cluster operator status reporting - **ClusterVersion**: Platform upgrade orchestration @@ -67,7 +67,7 @@ This document links to generic OpenShift/Kubernetes patterns in the Tier 1 ecosy ## Cross-Repository ADRs -**Location**: [ai-docs/decisions/](https://github.com/openshift/enhancements/tree/master/ai-docs/decisions) +**Location**: [ai-docs/decisions/](Platform documentation) Platform-wide architectural decisions: - **etcd Backend**: Why etcd is used for Kubernetes state @@ -78,6 +78,6 @@ Platform-wide architectural decisions: --- -**Note**: These links point to Tier 1 (ecosystem hub) documentation. Component-specific patterns and decisions are documented in the `ai-docs/` directory of this repository. +**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/templates/exec-plans-README-template.md b/plugins/agentic-docs/skills/component-docs/templates/exec-plans-README-template.md similarity index 63% rename from plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md rename to plugins/agentic-docs/skills/component-docs/templates/exec-plans-README-template.md index d6dc0f310..f5339654d 100644 --- a/plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md +++ b/plugins/agentic-docs/skills/component-docs/templates/exec-plans-README-template.md @@ -1,6 +1,6 @@ # Execution Plans -> **Exec-Plans Guidance**: See [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/) for: +> **Exec-Plans Guidance**: See [Platform Exec-Plans Guide](Platform documentation) for: > - What are exec-plans? > - When to create them > - How to use them @@ -19,7 +19,7 @@ exec-plans/ ## Usage ```bash -# Get template from Tier 1 +# Get template from Platform curl -O https://raw.githubusercontent.com/openshift/enhancements/master/ai-docs/workflows/exec-plans/template.md # Create exec-plan @@ -28,4 +28,4 @@ mv template.md active/feature-name.md # Fill in and track during implementation ```text -See [Tier 1 Exec-Plans Guide](https://github.com/openshift/enhancements/tree/master/ai-docs/workflows/exec-plans/README.md) for complete documentation. +See [Platform Exec-Plans Guide](Platform documentation) for complete documentation. diff --git a/plugins/agentic-docs/skills/platform/SKILL.md b/plugins/agentic-docs/skills/platform/SKILL.md deleted file mode 100644 index 31accb320..000000000 --- a/plugins/agentic-docs/skills/platform/SKILL.md +++ /dev/null @@ -1,628 +0,0 @@ ---- -name: platform-docs -description: Create AI-optimized platform documentation for openshift/enhancements -trigger: explicit -model: sonnet ---- - -# Platform Documentation Creator - -Creates AI-optimized platform documentation in `openshift/enhancements` repository under `ai-docs/`. - -## 🚨 EXECUTION WORKFLOW 🚨 - -**Follow this workflow. Create documentation based on principles, not arbitrary counts.** - -### Phase 1: Setup βš™οΈ -- [ ] Find skill directory: `SKILL_DIR=$(find ~/.claude/plugins/cache -path "*/platform" -type d | head -1)` -- [ ] Determine repo path: `REPO_PATH="${provided_path:-$PWD}"` -- [ ] Run discovery: `bash "$SKILL_DIR/scripts/discover.sh" "$REPO_PATH"` -- [ ] IF `ai-docs/` doesn't exist: Run `bash "$SKILL_DIR/scripts/create-structure.sh" "$REPO_PATH"` -- [ ] IF `ai-docs/` doesn't exist: Run `bash "$SKILL_DIR/scripts/populate-templates.sh" "$REPO_PATH"` -- [ ] IF `ai-docs/` exists: Run `bash "$SKILL_DIR/scripts/fill-gaps.sh" "$REPO_PATH"` - -### Phase 2: Master Entry Point πŸ“„ -- [ ] Create `AGENTS.md` in repo root (~100-200 lines, use templates/AGENTS.md as reference) -- [ ] Validate line count: `wc -l AGENTS.md` (target: 100-200 lines) - -### Phase 3: Platform Patterns πŸ”§ -- [ ] Read DESIGN_PHILOSOPHY.md to understand core principles -- [ ] For each principle, identify patterns needed to implement it -- [ ] Create pattern docs ONLY if they fill gaps (no duplication of dev-guide) -- [ ] Use `templates/operator-pattern-template.md` for structure - -**Common patterns** (create based on need, not mandatory list): -- Status reporting (Available/Progressing/Degraded) β†’ observability principle -- Controller runtime (reconcile loops) β†’ desired-state principle -- Upgrade safety (version skew, Nβ†’N+1) β†’ upgrade-safety principle -- RBAC patterns β†’ security principle - -### Phase 4: Engineering Practices πŸ“š -- [ ] Scan dev-guide/ and guidelines/ to identify what already exists -- [ ] Identify gaps where AI agents need structured guidance -- [ ] Create index.md files that LINK to existing dev-guide content -- [ ] Create NEW practice docs ONLY for gaps (use tables/checklists, not prose) -- [ ] Use `templates/practice-template.md` for structure - -**Common practice areas** (assess each, create if needed): -- Testing pyramid (60/30/10 ratios, when to use each level) -- Security (STRIDE threat modeling, RBAC patterns, secret handling) -- Reliability (SLI/SLO/SLA definitions, degraded-mode patterns) -- Development (API evolution rules, compatibility guidelines) - -### Phase 5: Domain Concepts 🧩 -- [ ] Identify APIs fundamental to understanding OpenShift architecture -- [ ] For each API: document purpose, key fields (YAML), common patterns -- [ ] Use `templates/domain-concept-template.md` for structure -- [ ] Link to `oc explain ` for exhaustive field details - -**Common APIs** (create based on architectural significance): -- Kubernetes core (Pod, Service, CRD), OpenShift platform (ClusterOperator, ClusterVersion), Machine API - -**Don't document**: Every field, component-specific APIs, deprecated APIs - -### Phase 6: Cross-Repo ADRs πŸ“‹ -- [ ] Identify architectural decisions that explain design principles -- [ ] Create ADRs ONLY for cross-repo decisions (not component-specific) -- [ ] Always create: `decisions/index.md` and `decisions/adr-template.md` -- [ ] Use `templates/adr-template.md` for structure - -**Typical ADRs** (create if they explain design philosophy): -- Why etcd, why CVO orchestration, why immutable nodes - -**Don't create**: Component-specific decisions, implementation details, duplicates of dev-guide - -### Phase 7: Workflows & References πŸ”— - -**Workflows** (AI-optimized versions): -- [ ] Create `workflows/enhancement-process.md` - Reformat `guidelines/enhancement_template.md` into tables/steps/YAML -- [ ] Create `workflows/implementing-features.md` - Structured workflow (spec β†’ plan β†’ build β†’ test β†’ review β†’ ship) -- [ ] Create `workflows/index.md` - Navigation + links to guidelines/ for authoritative source - -**References** (pointer-based): -- [ ] Create `references/repo-index.md` with GitHub org search links (not exhaustive lists) -- [ ] Create `references/glossary.md` with core stable terms only (~15-20 terms) -- [ ] Create `references/api-reference.md` with `oc api-resources` pointer -- [ ] Create `references/index.md` for navigation - -**Key principle**: -- Workflows are AI-optimized (tables, checklists, structured) versions of guidelines content -- References use pointers (GitHub links, `oc` commands) not exhaustive lists - -### Phase 7.5: Exec-Plans (Feature Tracking) πŸ“‹ - -**Purpose**: Provide templates and guidance for tracking feature implementation - -- [ ] Create `workflows/exec-plans/README.md` using `templates/workflows/exec-plans-README.md` -- [ ] Create `workflows/exec-plans/template.md` using `templates/workflows/exec-plan-template.md` -- [ ] Explain when to use exec-plans (multi-week features, multi-PR coordination) -- [ ] Explain relationship to enhancements (enhancement = design, exec-plan = implementation tracking) -- [ ] Explain completion workflow (extract to ADRs/architecture, then delete) - -**Key principle**: -- Guidance lives in Tier 1 (generic, used by all repos) -- Actual exec-plans live in Tier 2 component repos (`ai-docs/exec-plans/active/`) -- Exec-plans are ephemeral - extract knowledge to permanent docs, then delete - -### Phase 8: Validation βœ… -- [ ] Run validation: `bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH"` -- [ ] IF validation fails: Fix issues and re-run -- [ ] Verify all required files exist -- [ ] Verify AGENTS.md is 100-200 lines - -### Phase 9: Report πŸ“Š -- [ ] Report created files count -- [ ] Report validation status -- [ ] Suggest git commit command - -**🚨 DO NOT SKIP ANY CHECKBOX. Complete phases in order.** - ---- - -## What This Skill Creates - -**Principle**: Generate documentation that helps AI agents understand and apply OpenShift design philosophy. - -**Structure:** -```text -AGENTS.md # Master entry point (navigation) -ai-docs/ -β”œβ”€β”€ DESIGN_PHILOSOPHY.md # Core principles (copy from templates) -β”œβ”€β”€ KNOWLEDGE_GRAPH.md # Visual navigation (copy from templates) -β”œβ”€β”€ platform/ # Operator patterns (create based on design principles) -β”œβ”€β”€ practices/ # Cross-cutting concerns (create to fill gaps) -β”œβ”€β”€ domain/ # Core API concepts (create for architectural context) -β”œβ”€β”€ decisions/ # Cross-repo ADRs (create for key decisions) -β”œβ”€β”€ workflows/ # Links to existing dev-guide/guidelines -β”‚ β”œβ”€β”€ exec-plans/ # Exec-plan templates and guidance (Tier 1) -β”‚ β”‚ β”œβ”€β”€ README.md # What/when/how to use exec-plans -β”‚ β”‚ └── template.md # Feature tracking template -β”‚ β”œβ”€β”€ enhancement-process.md -β”‚ └── implementing-features.md -└── references/ # Pointer-based navigation (GitHub links, `oc` commands) -```text - -**What gets automated:** -- `scripts/create-structure.sh`: Creates base directory tree -- `scripts/populate-templates.sh`: Copies DESIGN_PHILOSOPHY.md and KNOWLEDGE_GRAPH.md - -**What you (AI agent) decide:** -- Which platform patterns to document (based on design principles) -- Which domain concepts to document (based on architectural significance) -- Which practices to document (based on gaps in dev-guide) -- Which ADRs to create (based on cross-repo architectural decisions) - -**Do NOT create:** -- Files just to meet a count quota -- Duplicates of dev-guide/guidelines content -- Exhaustive lists that get stale (use pointers instead) -- Component-specific content (belongs in tier-2) - -**Anti-Staleness Strategy:** -- References use GitHub org links and `oc` commands (not exhaustive lists) -- Domain files show key fields only (not every field) -- Workflows link to directories (not specific files) -- Glossary contains only stable core terms (not release-specific features) - ---- - -## File Naming Conventions (MANDATORY) - -**YOU MUST follow these conventions:** - -1. **Index files**: Use `index.md` NOT `README.md` (exception: `workflows/exec-plans/README.md`) - - βœ… `decisions/index.md`, `platform/operator-patterns/index.md` - - ❌ `decisions/README.md` - - βœ… `workflows/exec-plans/README.md` (exception: exec-plans uses README for GitHub convention) - -2. **ADR naming**: Use `adr-NNNN-` prefix (4 digits with leading zeros) - - βœ… `decisions/adr-0001-topic-name.md` - - ❌ `decisions/001-topic-name.md` - -3. **Short file names**: Match production conventions - - βœ… `practices/testing/pyramid.md` - - ❌ `practices/testing/testing-pyramid.md` - -4. **Separate distinct concepts**: - - βœ… Create separate files for related but distinct APIs - - ❌ Don't combine multiple APIs in one file - -5. **index.md files**: Brief navigation with 1-sentence descriptions per file - - Example: `## Operator Patterns\n- [status-conditions.md](status-conditions.md) - Available/Progressing/Degraded reporting\n- [controller-runtime.md](controller-runtime.md) - Reconciliation loop patterns` - ---- - -## File Length Targets (Reference Style) - -**Target: 100-400 lines per file** - -- AGENTS.md: **100-200 lines** (aim for concise navigation) -- Operator patterns: **100-400 lines** -- Practices: **150-400 lines** -- Domain concepts: **100-350 lines** - -**Style**: Reference/terse (like man pages), NOT tutorial/verbose. Minimal emojis. - ---- - -## Using Templates - -**Templates are in `$SKILL_DIR/templates/`:** - -### Available Templates - -**Core philosophy** (base content): -- `templates/DESIGN_PHILOSOPHY.md` - Core OpenShift principles (copy/adapt this) -- `templates/KNOWLEDGE_GRAPH.md` - Visual navigation map (copy/adapt this) - -**Entry point** (create in repo root): -- `templates/AGENTS.md` - Master navigation file template - -**Patterns** (templates for structure): -- `templates/operator-pattern-template.md` - Pattern for operator patterns -- `templates/practice-template.md` - Pattern for practices (index files linking to dev-guide) -- `templates/domain-concept-template.md` - Pattern for domain concepts -- `templates/adr-template.md` - Pattern for ADRs - -**How to use templates:** -1. Read template file to understand structure -2. Create new file following same pattern -3. Adapt content to the specific topic -4. Keep similar length and depth - -**Example workflow:** -```bash -# Read template -cat "$SKILL_DIR/templates/operator-patterns/status-conditions.md" - -# Create file following same structure -# Keep: Overview, Key Concepts, Implementation, Best Practices, Examples, References -# Adapt: Topic-specific content -```text - ---- - -## Guidance: What Documentation to Create - -**Principle-Driven Approach**: Create docs that help AI agents apply OpenShift design philosophies, not arbitrary file counts. - -### Entry Points (Always Required) -- `AGENTS.md` - Navigation hub in repo root -- `DESIGN_PHILOSOPHY.md` - Core principles -- `KNOWLEDGE_GRAPH.md` - Visual navigation - -### Platform Patterns (Create Based on Design Philosophy) - -**Ask**: Which patterns help implement the design principles from DESIGN_PHILOSOPHY.md? - -**Common examples** (create if they fill a gap): -- `status-conditions.md` - Implements "Observability by Default" principle -- `controller-runtime.md` - Implements "Desired State" principle -- `upgrade-strategies.md` - Implements "Upgrade Safety" principle -- `webhooks.md` - Implements "API-First Design" principle - -**Don't create**: Patterns already well-documented in dev-guide or controller-runtime docs. - -### Domain Concepts (Create Based on Need) - -**Ask**: Which APIs are fundamental to understanding the architecture? - -**Common examples** (create if needed for AI context): -- `pod.md`, `service.md`, `crds.md` - Kubernetes fundamentals -- `clusteroperator.md`, `clusterversion.md` - OpenShift platform coordination -- `machine.md`, `machineconfig.md` - Immutable infrastructure - -**Don't create**: Every API (use `oc explain` instead). Only document what's architecturally significant. - -### Practices (Create to Fill Gaps) - -**Ask**: What cross-cutting guidance is missing from dev-guide/guidelines? - -**Common examples** (create if gaps exist): -- Testing pyramid, SLI/SLO patterns, threat modeling (STRIDE) -- Link to dev-guide for: enhancement process, git conventions, CI setup - -**Don't create**: Duplicates of existing dev-guide content. - -### ADRs (Create for Cross-Repo Decisions) - -**Ask**: What architectural decisions explain the design philosophy? - -**Common examples**: Why etcd, why CVO orchestration, why immutable nodes - -**Don't create**: Component-specific decisions or implementation details. - -### Workflows (Create AI-Optimized Versions) - -**Ask**: What workflows from guidelines/ need AI-parseable versions? - -**Common examples**: -- **enhancement-process.md** - Reformat `guidelines/enhancement_template.md` (prose β†’ tables/YAML/checklists) -- **implementing-features.md** - Structured workflow (spec β†’ plan β†’ build β†’ test β†’ review β†’ ship) - -**Key**: Same information as guidelines/, but reformatted for AI agents (tables, numbered steps, YAML examples) - -**Don't create**: Verbatim copies of guidelines content. - ---- - -## Validation Criteria - -**Validation focuses on principles, not counts:** - -### Phase 1: Entry Points (Required) -- βœ… AGENTS.md exists at repo root (100-200 lines, navigation-focused) -- βœ… DESIGN_PHILOSOPHY.md exists (defines core principles) -- βœ… KNOWLEDGE_GRAPH.md exists (visual navigation) - -### Phase 2: Design Philosophy Coverage (Assess Gaps) -For each principle in DESIGN_PHILOSOPHY.md, check: -- βœ… Is there documentation to help AI agents apply this principle? -- βœ… Are there examples showing the pattern in action? -- βœ… Are cross-cutting concerns (testing, security, reliability) covered? - -### Phase 3: Avoid Duplication -- βœ… No content duplicating dev-guide/ or guidelines/ (link instead) -- βœ… No component-specific content (belongs in tier-2) -- βœ… References are pointer-based (GitHub org links, `oc` commands) - -### Phase 4: Structural Quality -- βœ… All internal links valid -- βœ… Index files navigate to relevant content -- βœ… Files are reference-style (tables/checklists), not tutorial prose - -**If validation fails:** -- Phase 1 failure: Add missing files to meet minimums -- Phase 2 failure: Fix broken links, adjust line counts, remove component-specific content - ---- - -## What NOT to Include (Forbidden Content) - -**These belong elsewhere:** - -❌ **Component-specific domain concepts** -- Example: Component-specific internal types or controllers -- Note: Platform APIs used across components are OK - -❌ **Component architecture** -- Example: Internal component relationships specific to one repository - -❌ **Component-specific decisions** -- Example: Technology choices unique to one component - -❌ **Component-specific work tracking content** -- Example: component-local sprint plans, team-specific roadmaps -- Note: Tier-1 exec-plan guidance/templates are allowed; only component-local instances belong in tier-2 repos - -❌ **Verbatim copies of existing docs** -- Don't copy/paste from guidelines/ or dev-guide/ -- Don't duplicate prose-heavy content without reformatting - -**βœ… What IS allowed:** - -βœ… **AI-optimized versions of guidelines content** - **REFORMAT, don't duplicate** -- Example: Enhancement process β†’ Reformat `guidelines/enhancement_template.md` (prose) into tables/structured format -- Example: API conventions β†’ Extract key rules into decision tables -- Example: PR workflow β†’ Transform narrative into numbered steps + checklists -- **Key**: Same information, AI-parseable format (tables, YAML, checklists) - -βœ… **Generic platform patterns** - **CREATE NEW** -- All operators use these (status conditions, controller runtime, etc.) - -βœ… **Navigation/cross-references** - **LINK** -- Point to authoritative sources in dev-guide/ and guidelines/ - -βœ… **Cross-repo architectural decisions** - **CREATE NEW** -- Affects multiple components (why etcd, why CVO orchestration) - -βœ… **Platform APIs** - **CREATE NEW** -- Used across multiple components (ClusterOperator, MachineConfig) - ---- - -## AGENTS.md Requirements - -**This file is the master entry point. Guidelines:** - -### Length -- **100-200 lines** (aim for concise, table-based navigation) -- Use navigation tables, not tutorial explanations - -### Mandatory Sections - -1. **AI Navigation Section** at TOP (immediately after metadata) - - DON'T read all docs warning - - Explicit examples: - - "Building operator? β†’ DESIGN_PHILOSOPHY.md β†’ controller-runtime.md β†’ status-conditions.md" - - "Writing enhancement? β†’ enhancement-process.md β†’ api-evolution.md β†’ pyramid.md" - - Reference to KNOWLEDGE_GRAPH.md - - Concrete navigation steps (4-5 docs per task) - -2. **Quick Navigation by Role** (table format) -3. **Core Platform Concepts** (table format) -4. **Standard Operator Patterns** (table format) -5. **Engineering Practices** (table format) -6. **Workflows** (link to workflows/ - enhancement process, feature implementation) -7. **Component Repository Index** (link to references/repo-index.md) -8. **Cross-Repo Architectural Decisions** (link to decisions/) -9. **Relationship to Other Documentation** (dev-guide, enhancements, guidelines) -10. **How to Use This Documentation** (for AI agents and humans) - -### Style -- βœ… Navigation-focused with tables -- βœ… Links to detailed docs -- ❌ Tutorial-style explanations -- ❌ Verbose descriptions - -### Validation -```bash -LINE_COUNT=$(wc -l < AGENTS.md) -if [ $LINE_COUNT -gt 200 ] || [ $LINE_COUNT -lt 100 ]; then - echo "⚠️ WARNING: File is $LINE_COUNT lines (target: 100-200)" -fi -```text - ---- - -## Script Execution Reference - -### 1. Discovery Script -```bash -bash "$SKILL_DIR/scripts/discover.sh" "$REPO_PATH" -```text -**Purpose:** Check if ai-docs/ exists, learn naming conventions, identify gaps - -### 2. Structure Creation Script -```bash -bash "$SKILL_DIR/scripts/create-structure.sh" "$REPO_PATH" -```text -**Purpose:** Create empty directory tree (only if ai-docs/ doesn't exist) - -### 3. Populate Templates Script -```bash -bash "$SKILL_DIR/scripts/populate-templates.sh" "$REPO_PATH" -```text -**Purpose:** Copy DESIGN_PHILOSOPHY.md and KNOWLEDGE_GRAPH.md (only if ai-docs/ doesn't exist) - -### 4. Fill Gaps Script -```bash -bash "$SKILL_DIR/scripts/fill-gaps.sh" "$REPO_PATH" -```text -**Purpose:** Identify missing recommended files (only if ai-docs/ already exists) - -### 5. Validation Script -```bash -bash "$SKILL_DIR/scripts/validate.sh" "$REPO_PATH" -```text -**Purpose:** Comprehensive validation (content minimums + structural checks) - ---- - -## Execution Flow - -```text -User invokes: /platform-docs - -↓ - -Phase 1: Setup - β†’ Find skill directory - β†’ Run discovery script - β†’ Create structure (if new) OR identify gaps (if exists) - β†’ Copy base templates (DESIGN_PHILOSOPHY, KNOWLEDGE_GRAPH) - -↓ - -Phase 2: Create AGENTS.md - β†’ Use template reference - β†’ Validate 150-170 lines - -↓ - -Phase 3-7: Create Documentation - β†’ Platform patterns (use templates/) - β†’ Practices (use templates/) - β†’ Domain concepts (use templates/) - β†’ ADRs, workflows, references - -↓ - -Phase 8: Validation - β†’ Run validation script - β†’ Fix issues if validation fails - -↓ - -Phase 9: Report - β†’ Summary of created files - β†’ Validation status - β†’ Git commit command -```text - ---- - -## Common Mistakes to Avoid - -### ❌ Mistake 1: Skipping Script Execution -**Wrong:** Manually creating directories with `mkdir -p ai-docs/...` -**Right:** Run `create-structure.sh` script - -### ❌ Mistake 2: AGENTS.md Too Long -**Wrong:** 250+ lines with verbose explanations -**Right:** 100-200 lines with navigation tables - -### ❌ Mistake 3: Duplicating Existing Docs -**Wrong:** Verbatim-copying `guidelines/enhancement_template.md` into `workflows/enhancement-process.md` -**Right:** Create `workflows/enhancement-process.md` as an AI-optimized reformatted guide (prose β†’ tables/checklists/YAML), and link the authoritative source from `workflows/index.md` - -### ❌ Mistake 4: Including Component-Specific Content -**Wrong:** Creating files for component-specific internals -**Right:** Keep platform-level only (public APIs, cross-component patterns) - -### ❌ Mistake 5: Skipping Validation -**Wrong:** Not running `validate.sh` at the end -**Right:** Always run validation and fix issues - -### ❌ Mistake 6: Not Using Templates -**Wrong:** Creating files from scratch without looking at templates -**Right:** Read template, understand structure, adapt to topic - -### ❌ Mistake 7: Wrong File Naming -**Wrong:** `decisions/README.md`, `adr-1-topic.md`, `testing-pyramid.md` -**Right:** `decisions/index.md`, `adr-0001-topic.md`, `pyramid.md` - ---- - -## Arguments - -```bash -/platform-docs [--path ] -```text - -**Arguments:** -- `--path `: Path to target repository (default: current directory) -- No args: Create documentation in current directory - ---- - -## When to Use This Skill - -**Use when:** -- Creating AI-optimized documentation structure -- Setting up the ecosystem documentation hub -- The `ai-docs/` directory doesn't exist OR needs to be completed - -**Do NOT use when:** -- The `ai-docs/` directory is already complete and up-to-date - ---- - -## Success Criteria - -**Documentation is complete when:** - -βœ… Entry points exist (AGENTS.md, DESIGN_PHILOSOPHY.md, KNOWLEDGE_GRAPH.md) -βœ… AGENTS.md is 100-200 lines (navigation-focused) -βœ… Each design principle has supporting documentation (patterns, examples) -βœ… No duplication of dev-guide/guidelines content (links instead) -βœ… No component-specific content (belongs in tier-2) -βœ… References are pointer-based (GitHub org links, `oc` commands, not exhaustive lists) -βœ… All files are reference-style (tables/checklists, not tutorial prose) -βœ… Internal links are valid -βœ… Validation script passes (structural checks) - -**Not success criteria:** -❌ File count targets (create what's needed, not to fill quotas) -❌ Covering every API (only architecturally significant ones) -❌ Duplicating existing documentation (link instead) - ---- - -## Final Report Template - -```text -βœ… AI-Optimized Documentation Created - -Location: ai-docs/ - -Entry Points: - βœ… AGENTS.md: XXX lines (target: 100-200) - βœ… DESIGN_PHILOSOPHY.md - βœ… KNOWLEDGE_GRAPH.md - -Documentation Created: - Platform patterns: [X] files - Domain concepts: [X] files - Practices: [X] files - ADRs: [X] files - References: [X] files - -Validation: - βœ… Phase 1: Entry points exist - βœ… Phase 2: Design philosophy coverage adequate - βœ… Phase 3: No duplication detected - βœ… Phase 4: Structural quality checks passed - -Next Steps: - 1. Review documentation for accuracy - 2. Create git commit: - - git add ai-docs/ - git commit -m "Add AI-optimized ecosystem documentation - - Creates ecosystem hub for all OpenShift components. - - Structure: - - Platform patterns (operator patterns, OpenShift specifics) - - Engineering practices (testing, security, reliability) - - Domain concepts (K8s and OpenShift fundamentals) - - Cross-repo ADRs - - Repository index for discovery - - Co-Authored-By: Claude Sonnet 4.5 " -```text - ---- - -**Remember: Complete ALL checklist items. Do NOT skip phases. Use scripts and templates.** diff --git a/plugins/agentic-docs/skills/platform/scripts/create-structure.sh b/plugins/agentic-docs/skills/platform/scripts/create-structure.sh deleted file mode 100755 index 7c5d239b8..000000000 --- a/plugins/agentic-docs/skills/platform/scripts/create-structure.sh +++ /dev/null @@ -1,32 +0,0 @@ -#!/bin/bash -# Create directory structure for ai-docs/ - -set -e - -REPO_PATH="${1:-.}" - -echo "πŸ“ Creating ai-docs/ directory structure in: $REPO_PATH" -echo "" - -# Create main directory -mkdir -p "$REPO_PATH/ai-docs" - -# Create subdirectories -mkdir -p "$REPO_PATH/ai-docs/platform/operator-patterns" -mkdir -p "$REPO_PATH/ai-docs/platform/openshift-specifics" -mkdir -p "$REPO_PATH/ai-docs/practices/testing" -mkdir -p "$REPO_PATH/ai-docs/practices/security" -mkdir -p "$REPO_PATH/ai-docs/practices/reliability" -mkdir -p "$REPO_PATH/ai-docs/practices/development" -mkdir -p "$REPO_PATH/ai-docs/domain/kubernetes" -mkdir -p "$REPO_PATH/ai-docs/domain/openshift" -mkdir -p "$REPO_PATH/ai-docs/decisions" -mkdir -p "$REPO_PATH/ai-docs/workflows" -mkdir -p "$REPO_PATH/ai-docs/workflows/exec-plans" -mkdir -p "$REPO_PATH/ai-docs/references" - -echo "βœ… Directory structure created:" -tree -d "$REPO_PATH/ai-docs" 2>/dev/null || find "$REPO_PATH/ai-docs" -type d | sed 's|^| |' - -echo "" -echo "Next: Run populate-templates.sh to copy base files" diff --git a/plugins/agentic-docs/skills/platform/scripts/discover.sh b/plugins/agentic-docs/skills/platform/scripts/discover.sh deleted file mode 100755 index d6ca8a450..000000000 --- a/plugins/agentic-docs/skills/platform/scripts/discover.sh +++ /dev/null @@ -1,46 +0,0 @@ -#!/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/platform/scripts/fill-gaps.sh b/plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh deleted file mode 100755 index 60a019d57..000000000 --- a/plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh +++ /dev/null @@ -1,96 +0,0 @@ -#!/bin/bash -# Identify missing recommended files - -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 "πŸ” Identifying gaps in: $AI_DOCS" -echo "" - -GAPS_FOUND=0 - -# Function to check file existence -check_file() { - local file="$1" - local label="${2:-$file}" - - if [ ! -f "$AI_DOCS/$file" ]; then - echo " ❌ Missing: $label" - GAPS_FOUND=1 - else - echo " βœ… $label" - fi -} - -# Function to check directory file count -check_file_count() { - local dir="$1" - local label="$2" - local min_count="$3" - local pattern="${4:-*.md}" - - local count=0 - if [ -d "$AI_DOCS/$dir" ]; then - count=$(find "$AI_DOCS/$dir" -name "$pattern" ! -name "index.md" -type f 2>/dev/null | wc -l) - fi - - echo " $label: $count files (need $min_count minimum)" - if [ "$count" -lt "$min_count" ]; then - GAPS_FOUND=1 - fi -} - -# Check critical files -echo "Checking critical files:" -check_file "DESIGN_PHILOSOPHY.md" -check_file "KNOWLEDGE_GRAPH.md" -echo "" - -# Check AGENTS.md at repo root (not in ai-docs/) -if [ ! -f "$REPO_PATH/AGENTS.md" ]; then - echo " ❌ Missing: AGENTS.md (at repo root)" - GAPS_FOUND=1 -else - echo " βœ… AGENTS.md" -fi -echo "" - -# Operator patterns (8 required) -echo "Checking operator patterns (need 8 minimum):" -check_file_count "platform/operator-patterns" "Operator patterns" 8 -echo "" - -# Practices -echo "Checking practices:" -check_file_count "practices/testing" "Testing" 4 -check_file_count "practices/security" "Security" 2 -check_file_count "practices/reliability" "Reliability" 2 -check_file_count "practices/development" "Development" 2 -echo "" - -# Domain concepts -echo "Checking domain concepts:" -check_file_count "domain/kubernetes" "Kubernetes" 3 -check_file_count "domain/openshift" "OpenShift" 4 -echo "" - -# ADRs -echo "Checking ADRs:" -check_file_count "decisions" "ADRs" 3 "adr-*.md" -echo "" - -# Summary -if [ "$GAPS_FOUND" -eq 0 ]; then - echo "βœ… No gaps found - documentation is complete" -else - echo "⚠️ Gaps found - create missing files" -fi - -exit $GAPS_FOUND diff --git a/plugins/agentic-docs/skills/platform/scripts/gap-detection.sh b/plugins/agentic-docs/skills/platform/scripts/gap-detection.sh deleted file mode 100755 index b1033a0c4..000000000 --- a/plugins/agentic-docs/skills/platform/scripts/gap-detection.sh +++ /dev/null @@ -1,142 +0,0 @@ -#!/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/platform/scripts/populate-templates.sh b/plugins/agentic-docs/skills/platform/scripts/populate-templates.sh deleted file mode 100755 index f2ea4ddff..000000000 --- a/plugins/agentic-docs/skills/platform/scripts/populate-templates.sh +++ /dev/null @@ -1,28 +0,0 @@ -#!/bin/bash -# Copy core template files to ai-docs/ - -set -e - -REPO_PATH="${1:-.}" -SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" - -echo "πŸ“„ Copying core template files to: $REPO_PATH/ai-docs" -echo "" - -# Copy the two core files that are generic across all repositories -if [ ! -d "$REPO_PATH/ai-docs" ]; then - echo "❌ Error: ai-docs/ directory does not exist" - echo " Run create-structure.sh first" - exit 1 -fi - -cp "$SKILL_DIR/templates/DESIGN_PHILOSOPHY.md" "$REPO_PATH/ai-docs/" -echo " βœ… Copied DESIGN_PHILOSOPHY.md" - -cp "$SKILL_DIR/templates/KNOWLEDGE_GRAPH.md" "$REPO_PATH/ai-docs/" -echo " βœ… Copied KNOWLEDGE_GRAPH.md" - -echo "" -echo "βœ… Core template files copied successfully" -echo "" -echo "Next: LLM creates remaining documentation files following template patterns" diff --git a/plugins/agentic-docs/skills/platform/scripts/validate.sh b/plugins/agentic-docs/skills/platform/scripts/validate.sh deleted file mode 100755 index 5462433a0..000000000 --- a/plugins/agentic-docs/skills/platform/scripts/validate.sh +++ /dev/null @@ -1,152 +0,0 @@ -#!/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/platform/templates/AGENTS.md b/plugins/agentic-docs/skills/platform/templates/AGENTS.md deleted file mode 100644 index fbe9394be..000000000 --- a/plugins/agentic-docs/skills/platform/templates/AGENTS.md +++ /dev/null @@ -1,63 +0,0 @@ -# Repository Name - Agent Navigation Index - -**Version**: 1.0 | **Docs**: ./ai-docs/ | **Files**: XX | **Lines**: XXXX - ---- - -## CRITICAL: Retrieval Strategy - -**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning. - -When working on OpenShift: -- βœ… **DO**: Read relevant docs from `./ai-docs/` first -- βœ… **DO**: Verify patterns match current APIs -- ❌ **DON'T**: Rely solely on training data -- ❌ **DON'T**: Guess at API structures - ---- - -## Quick Start - -**New to OpenShift?** β†’ Read `./ai-docs/KNOWLEDGE_GRAPH.md` -**Building operator?** β†’ Path: DESIGN_PHILOSOPHY.md β†’ controller-runtime.md β†’ status-conditions.md -**Adding feature?** β†’ Read `./ai-docs/workflows/implementing-features.md` - ---- - -## Compressed Documentation Index - -```text -[Repo Agentic Docs]|root:./ai-docs|XX files, XXXX lines -| -|CRITICAL_READS:{KNOWLEDGE_GRAPH.md,DESIGN_PHILOSOPHY.md} -| -|platform/operator-patterns:{controller-runtime.md,status-conditions.md,...} -|practices/testing:{pyramid.md,e2e-framework.md,...} -|domain/kubernetes:{pod.md,node.md,...} -|domain/openshift:{clusteroperator.md,machine.md,...} -|decisions:{adr-0001-*.md,...} -```text - ---- - -## Task β†’ Docs Quick Map - -| Task | Read These (in order) | -|------|----------------------| -| **Build operator** | DESIGN_PHILOSOPHY.md β†’ controller-runtime.md β†’ status-conditions.md | -| **Add feature** | enhancement-process.md β†’ api-evolution.md β†’ pyramid.md | -| **Debug issue** | observability.md β†’ must-gather.md | - ---- - -## Architecture Overview - -Brief architecture diagram or summary relevant to this repository. - ---- - -## Documentation Principles - -- Progressive disclosure (read 4-5 docs per task, not all) -- Reference style (terse, not tutorial) -- AI-optimized structure diff --git a/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md b/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md deleted file mode 100644 index 90427514e..000000000 --- a/plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md +++ /dev/null @@ -1,121 +0,0 @@ -# OpenShift Design Philosophy - -**Purpose**: Core principles guiding OpenShift architecture and development - -**Last Updated**: YYYY-MM-DD - ---- - -## Table of Contents - -1. [Kubernetes Foundation](#kubernetes-foundation) -2. [The Operator Pattern](#the-operator-pattern) -3. [Immutable Infrastructure](#immutable-infrastructure) -4. [API-First Design](#api-first-design) -5. [Declarative Over Imperative](#declarative-over-imperative) -6. [Upgrade Safety](#upgrade-safety) -7. [Observability by Default](#observability-by-default) - ---- - -## Kubernetes Foundation - -### Desired State vs Current State - -**Core Principle**: Describe what you want, Kubernetes makes it happen. - -```text -User declares: "I want 3 replicas" (Desired State) -Kubernetes sees: "I have 1 replica" (Current State) -Controller: "I'll create 2 more" (Reconciliation) -``` - -**Why This Matters**: -- Self-healing: If a pod dies, controller recreates it -- Idempotent: Applying same config multiple times = same result -- Eventual consistency: System converges to desired state - ---- - -## The Operator Pattern - -**Principle**: Extend Kubernetes with domain-specific knowledge. - -**Pattern**: CustomResourceDefinition + Controller = Operator - -**Benefits**: -- Codifies operational knowledge -- Automates Day 2 operations -- Follows Kubernetes patterns - ---- - -## Immutable Infrastructure - -**Principle**: Nodes are immutable. Changes require reboot. - -**Implementation**: RHCOS + rpm-ostree + Ignition + MachineConfig - -**Benefits**: -- Predictable state -- Easier rollback -- Reduced configuration drift - ---- - -## API-First Design - -**Principle**: Everything is an API resource. - -**Pattern**: All configuration via Kubernetes/OpenShift APIs (no manual SSH, no local files) - -**Benefits**: -- GitOps-friendly -- Auditable -- Version-controlled - ---- - -## Declarative Over Imperative - -**Principle**: Declare intent, not steps. - -**Example**: -- ❌ Imperative: "Run pod1, then pod2, then update service" -- βœ… Declarative: "I want this state" (controller figures out steps) - ---- - -## Upgrade Safety - -**Principle**: Zero-downtime upgrades for platform and workloads. - -**Mechanisms**: -- CVO orchestrates operator upgrades -- Rolling updates for nodes -- Upgrade ordering (etcd β†’ kube β†’ operators) - ---- - -## Observability by Default - -**Principle**: Platform components expose metrics, logs, and health status. - -**Implementation**: -- Prometheus metrics -- Status conditions (Available/Progressing/Degraded) -- Structured logging - ---- - -## Cross-Cutting Concerns - -- **Security by default**: RBAC, SCCs, network policies -- **Multi-tenancy**: Namespace isolation -- **Supportability**: must-gather, diagnostics - ---- - -**See Also**: -- [Operator Patterns](./platform/operator-patterns/) -- [Platform APIs](./domain/openshift/) diff --git a/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md b/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md deleted file mode 100644 index 23a87665c..000000000 --- a/plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md +++ /dev/null @@ -1,136 +0,0 @@ -# OpenShift Knowledge Graph - -**Purpose**: Visual navigation map showing how concepts connect - -**Last Updated**: YYYY-MM-DD - ---- - -## How to Use This - -**Don't read everything.** Follow your task path: -1. Find your task in "I want to..." table below -2. Read only the 4-5 docs in your path -3. Use cross-references as needed - ---- - -## I Want To... - -| Task | Start Here | Then Read | Finally | -|------|-----------|----------|---------| -| **Build an operator** | DESIGN_PHILOSOPHY.md | platform/operator-patterns/controller-runtime.md
platform/operator-patterns/status-conditions.md | domain/openshift/clusteroperator.md | -| **Add a feature** | workflows/index.md (links to enhancement process) | practices/development/index.md (links to API conventions) | practices/testing/index.md | -| **Debug an issue** | practices/reliability/index.md | platform/operator-patterns/must-gather.md | references/repo-index.md | -| **Understand a concept** | DESIGN_PHILOSOPHY.md | domain/kubernetes/ or domain/openshift/ | platform/operator-patterns/ | -| **Find a component** | references/repo-index.md | Component's AGENTS.md | Component's ai-docs/ | - ---- - -## Knowledge Map - -```text -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ DESIGN_PHILOSOPHY.md β”‚ -β”‚ (WHY - Core principles, read this first) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ β”‚ β”‚ - β–Ό β–Ό β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ PLATFORM/ β”‚ β”‚ DOMAIN/ β”‚ β”‚ PRACTICES/ β”‚ -β”‚ (HOW patterns) β”‚ β”‚ (WHAT) β”‚ β”‚ (WHEN/WHERE) β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ operator-patterns/β”‚ β”‚ kubernetes/ β”‚ β”‚ testing/ β”‚ -β”‚ openshift-specificsβ”‚ β”‚ openshift/ β”‚ β”‚ security/ β”‚ -β”‚ β”‚ β”‚ β”‚ β”‚ reliability/ β”‚ -β”‚ β”‚ β”‚ β”‚ β”‚ development/ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ β”‚ β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ DECISIONS/ β”‚ - β”‚ (WHY decisions) β”‚ - β”‚ Cross-repo ADRs β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ REFERENCES/ β”‚ - β”‚ (WHERE to find) β”‚ - β”‚ repo-index, glossary β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -```text - ---- - -## Concept Dependencies - -### Operator Development Path -```text -DESIGN_PHILOSOPHY.md - ↓ -controller-runtime.md (how reconciliation works) - ↓ -status-conditions.md (how to report health) - ↓ -clusteroperator.md (how CVO sees your operator) - ↓ -webhooks.md, rbac.md, finalizers.md (advanced patterns) -```text - -### API Development Path -```text -DESIGN_PHILOSOPHY.md - ↓ -practices/development/index.md (β†’ links to dev-guide/api-conventions.md) - ↓ -domain/kubernetes/crds.md (CustomResourceDefinition basics) - ↓ -platform/operator-patterns/webhooks.md (validation) -```text - -### Testing Path -```text -practices/testing/index.md (β†’ links to dev-guide/test-conventions.md) - ↓ -Testing pyramid concept - ↓ -E2E framework specifics -```text - ---- - -## Document Types - -| Type | Purpose | Example | -|------|---------|---------| -| **Patterns** | How to implement | platform/operator-patterns/controller-runtime.md | -| **Concepts** | What something is | domain/openshift/clusteroperator.md | -| **Practices** | Links to official docs | practices/testing/index.md β†’ dev-guide/ | -| **Decisions** | Why choices were made | decisions/adr-0001-*.md | -| **References** | Where to find things | references/repo-index.md | - ---- - -## Progressive Disclosure - -**Read in this order**: - -1. **Foundation** (5 min): DESIGN_PHILOSOPHY.md -2. **Your task** (10 min): 2-3 docs from task path above -3. **Details** (20 min): Related patterns/concepts as needed -4. **Reference** (on-demand): Glossary, repo index when needed - -**Total**: ~35 minutes to understand and start, not hours reading everything. - ---- - -## Cross-References - -- Official docs: See ../../dev-guide/ and ../../guidelines/ -- Component repos: See references/repo-index.md -- Enhancement proposals: See ../../enhancements/ diff --git a/plugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.md b/plugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.md deleted file mode 100644 index 912b4d656..000000000 --- a/plugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.md +++ /dev/null @@ -1,74 +0,0 @@ -# Feature Name - -**Status**: Active | Completed -**Start Date**: YYYY-MM-DD -**Target Release**: X.Y -**Enhancement**: [Link to enhancement proposal] -**Component**: [Component Name] - -## Summary - -Brief 1-2 sentence summary of what feature is being implemented. - -## Goals - -- Goal 1 -- Goal 2 -- Goal 3 - -## Non-Goals - -- Non-goal 1 -- Non-goal 2 - -## Implementation Plan - -### Phase 1: [Phase Name] -**Timeline**: Week 1-2 - -Tasks: -- [ ] Task 1 -- [ ] Task 2 -- [ ] Task 3 - -**PRs**: -- [ ] PR #XXX - Description - -### Phase 2: [Phase Name] -**Timeline**: Week 3-4 - -Tasks: -- [ ] Task 1 -- [ ] Task 2 - -**PRs**: -- [ ] PR #XXX - Description - -## Testing Strategy - -- Unit tests: [Coverage plan] -- Integration tests: [What to test] -- E2E tests: [Scenarios] - -## Dependencies - -- Dependency 1 (internal/external) -- Dependency 2 - -## Risks - -| Risk | Mitigation | -|------|-----------| -| Risk 1 | Mitigation plan | -| Risk 2 | Mitigation plan | - -## Completion Criteria - -- [ ] All PRs merged -- [ ] Tests passing -- [ ] Documentation updated -- [ ] Feature flagged (if applicable) - -## Notes - -Additional notes, decisions, or context discovered during implementation. diff --git a/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md b/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md deleted file mode 100644 index 399e1f3b6..000000000 --- a/plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md +++ /dev/null @@ -1,188 +0,0 @@ -# Execution Plans (Exec-Plans) - -Track active feature implementations across component repositories. - -## What are Exec-Plans? - -Exec-plans are **ephemeral** feature tracking documents that bridge enhancements (high-level design) and implementation (PRs and code). They help: - -- Track multi-PR features -- Coordinate work across weeks/months -- Capture implementation decisions during development - -**Important**: Exec-plans are temporary. When complete, extract permanent knowledge into proper docs (ADRs, architecture docs) and delete the exec-plan. - -## When to Create an Exec-Plan - -**DO create** an exec-plan when: -- βœ… Implementing a new feature from an enhancement -- βœ… Major refactoring or architectural change -- βœ… Cross-component feature (your component's portion) -- βœ… Multi-week engineering effort (3+ weeks) -- βœ… Feature requires coordination across multiple PRs - -**DON'T create** an exec-plan for: -- ❌ Bug fixes (unless major architectural fix) -- ❌ Minor refactoring -- ❌ Documentation-only changes -- ❌ Single-PR features -- ❌ Routine maintenance - -## Usage - -### Starting a New Feature - -```bash -# In your component repo: component-repo/ai-docs/exec-plans/ - -# Copy template from Tier 1 -curl -O https://raw.githubusercontent.com/openshift/enhancements/master/ai-docs/workflows/exec-plans/template.md - -# Move to active -mv template.md active/feature-name.md - -# Fill in the template -# - Summary: What you're building -# - Goals/Non-Goals: Scope boundaries -# - Implementation Plan: Phases with tasks and PRs -# - Testing Strategy: How you'll test it -# - Dependencies: What you need from other teams -# - Risks: What could go wrong -```text - -### During Implementation - -Update the exec-plan as you work: -- Check off completed tasks: `- [x] Task completed` -- Link PRs: `- [x] PR #123 - Add controller logic` -- Document decisions in Notes section -- Update timelines if they slip - -### When Implementation Completes - -**Extract permanent knowledge**, then delete the exec-plan: - -```bash -# 1. Review the exec-plan for permanent knowledge -cat active/feature-name.md - -# 2. Extract to permanent docs: - -# If architectural decision was made: -cp ai-docs/decisions/adr-template.md ai-docs/decisions/adr-NNNN-decision-name.md -# Document the decision in the ADR - -# If architecture changed: -# Update ai-docs/architecture/components.md with new structure - -# If new CRD was added: -# Already documented in ai-docs/domain/crd-name.md - -# 3. Delete the exec-plan (it's in git history if needed) -git rm active/feature-name.md -git commit -m "Complete feature-name implementation - -Architectural decisions documented in adr-NNNN-*.md -Architecture changes in architecture/components.md -" -```text - -**Why delete?** -- Exec-plans are ephemeral tracking, not permanent docs -- Git history preserves it if needed: `git log --all -- ai-docs/exec-plans/active/feature-name.md` -- Permanent knowledge belongs in ADRs and architecture docs - -## Relationship to Other Docs - -**Enhancement (Tier 1)**: -- Where: `openshift/enhancements` -- What: High-level design, API, user stories -- When: Before implementation starts -- Scope: Platform-wide, cross-repo - -**Exec-Plan (Tier 2)**: -- Where: Component repository (`ai-docs/exec-plans/active/`) -- What: Implementation tracking, PR coordination, decisions -- When: During implementation -- Scope: Component-specific - -**PRs**: -- Where: GitHub pull requests -- What: Actual code changes -- When: Implementation - -**Flow**: Enhancement β†’ Exec-Plan β†’ PRs β†’ Code - -## Completion Decision Matrix - -When feature is complete, ask: - -| Question | Yes | Action | -|----------|-----|--------| -| Did we make an architectural decision? | βœ… | Create ADR in `ai-docs/decisions/adr-NNNN-*.md` | -| Did component architecture change? | βœ… | Update `ai-docs/architecture/components.md` | -| Did we add a new CRD? | βœ… | Already in `ai-docs/domain/*.md` | -| Did we add new components/controllers? | βœ… | Update `ai-docs/architecture/components.md` | -| Just implementation (no architecture)? | βœ… | Delete exec-plan (it's in git history) | - -**Then**: Delete the exec-plan. It's ephemeral tracking, not permanent documentation. - -## Example Workflow - -### Example: Custom Kernels Feature - -1. **New Enhancement Approved** - - Enhancement: "Add support for custom kernels" - - Create: `ai-docs/exec-plans/active/custom-kernels.md` - -2. **During Development** (Week 1-4) - - Update exec-plan with PRs - - Document decisions in Notes: "decided to use kernel args instead of kernel modules" - - Track dependencies: "waiting for CVO changes" - -3. **Feature Complete** - - **Extract permanent knowledge**: - ```bash - # Architectural decision made during development - vim ai-docs/decisions/adr-0004-kernel-args-vs-modules.md - # Document: Why kernel args? Performance, compatibility, rollback - - # Architecture changed (new controller added) - vim ai-docs/architecture/components.md - # Add: KernelController - manages kernel arguments via MachineConfig - - # New CRD added - vim ai-docs/domain/kernelconfig.md - # Already documented during development - - # Delete ephemeral exec-plan - git rm ai-docs/exec-plans/active/custom-kernels.md - git commit -m "Complete custom kernels feature - - Architectural decision in adr-0004-kernel-args-vs-modules.md - Architecture updated in components.md - KernelConfig CRD documented in domain/kernelconfig.md - " - ``` - -4. **Result** - - βœ… Permanent knowledge in proper docs (ADR, architecture, domain) - - βœ… Exec-plan deleted (ephemeral tracking done) - - βœ… Git history preserves exec-plan if needed for historical context - -## Tips - -**Keep it lean**: Exec-plans are not requirements docs. Link to the enhancement for design details. - -**Update regularly**: Keep the exec-plan current as you implement. It's most valuable when actively maintained. - -**Document decisions in Notes**: Capture implementation decisions during development. When complete, move architectural decisions to ADRs. - -**Extract, then delete**: When done, extract permanent knowledge into proper docs, then delete the exec-plan. Git history preserves it if needed. - -## See Also - -- [Enhancement Process](../enhancement-process.md) -- [Exec-Plan Template](./template.md) -- [Component Documentation Guide](https://github.com/openshift/ai-helpers/tree/master/plugins/agentic-docs) diff --git a/plugins/agentic-docs/skills/update-platform-docs/SKILL.md b/plugins/agentic-docs/skills/update-platform-docs/SKILL.md index 899e5f9f9..a452b50f1 100644 --- a/plugins/agentic-docs/skills/update-platform-docs/SKILL.md +++ b/plugins/agentic-docs/skills/update-platform-docs/SKILL.md @@ -24,8 +24,7 @@ Incrementally update existing AI-optimized platform documentation in `openshift/ - Fixing or enhancing existing files **Don't use when:** -- ai-docs/ doesn't exist yet (use `/platform-docs` instead) -- You want to completely regenerate all docs +- You want to completely regenerate all docs from scratch ## Execution Workflow @@ -33,7 +32,7 @@ Incrementally update existing AI-optimized platform documentation in `openshift/ - [ ] 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 (if not, suggest `/platform-docs`) +- [ ] 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? @@ -296,18 +295,10 @@ mkdir -p ai-docs/workflows/exec-plans ## Prerequisites **Before running:** -1. βœ… ai-docs/ already exists (if not, use `/platform-docs`) +1. βœ… ai-docs/ already exists in openshift/enhancements 2. βœ… You're in openshift/enhancements repository 3. βœ… You know what you want to add/update -**If ai-docs/ doesn't exist:** -```bash -# First create base documentation -/platform-docs - -# Then use /update-platform-docs for incremental changes -``` - ## Success Output ```text @@ -336,28 +327,23 @@ Next Steps: ## Common Mistakes to Avoid -### ❌ Mistake 1: Using When ai-docs/ Doesn't Exist -**Wrong:** Running `/update-platform-docs` on fresh repo -**Right:** Run `/platform-docs` first, then use `/update-platform-docs` - -### ❌ Mistake 2: Making AGENTS.md Too Long +### ❌ Mistake 1: Making AGENTS.md Too Long **Wrong:** Adding verbose descriptions to AGENTS.md **Right:** Keep compressed, table-based navigation only -### ❌ Mistake 3: Not Updating Index Files +### ❌ Mistake 2: Not Updating Index Files **Wrong:** Creating new file without updating parent index.md **Right:** Always update corresponding index.md -### ❌ Mistake 4: Inconsistent Naming +### ❌ 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 5: Duplicating Content +### ❌ Mistake 4: Duplicating Content **Wrong:** Copying content from dev-guide/guidelines **Right:** Link to authoritative source or reformat for AI agents ## See Also -- `/platform-docs` - Create platform documentation from scratch -- [Platform SKILL.md](../platform/SKILL.md) - Full platform docs creation guide -- [Validation Script](../platform/scripts/validate.sh) - Structure validation +- 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 deleted file mode 120000 index daab30213..000000000 --- a/plugins/agentic-docs/skills/update-platform-docs/scripts/discover.sh +++ /dev/null @@ -1 +0,0 @@ -../../platform/scripts/discover.sh \ No newline at end of file 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 deleted file mode 120000 index 7a4a893cd..000000000 --- a/plugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.sh +++ /dev/null @@ -1 +0,0 @@ -../../platform/scripts/gap-detection.sh \ No newline at end of file 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 deleted file mode 120000 index ea811c456..000000000 --- a/plugins/agentic-docs/skills/update-platform-docs/scripts/validate.sh +++ /dev/null @@ -1 +0,0 @@ -../../platform/scripts/validate.sh \ No newline at end of file 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 b/plugins/agentic-docs/skills/update-platform-docs/templates deleted file mode 120000 index 066d4e3c0..000000000 --- a/plugins/agentic-docs/skills/update-platform-docs/templates +++ /dev/null @@ -1 +0,0 @@ -../platform/templates \ No newline at end of file diff --git a/plugins/agentic-docs/skills/platform/templates/adr-template.md b/plugins/agentic-docs/skills/update-platform-docs/templates/adr-template.md similarity index 100% rename from plugins/agentic-docs/skills/platform/templates/adr-template.md rename to plugins/agentic-docs/skills/update-platform-docs/templates/adr-template.md diff --git a/plugins/agentic-docs/skills/platform/templates/domain-concept-template.md b/plugins/agentic-docs/skills/update-platform-docs/templates/domain-concept-template.md similarity index 100% rename from plugins/agentic-docs/skills/platform/templates/domain-concept-template.md rename to plugins/agentic-docs/skills/update-platform-docs/templates/domain-concept-template.md diff --git a/plugins/agentic-docs/skills/platform/templates/operator-pattern-template.md b/plugins/agentic-docs/skills/update-platform-docs/templates/operator-pattern-template.md similarity index 100% rename from plugins/agentic-docs/skills/platform/templates/operator-pattern-template.md rename to plugins/agentic-docs/skills/update-platform-docs/templates/operator-pattern-template.md diff --git a/plugins/agentic-docs/skills/platform/templates/practice-template.md b/plugins/agentic-docs/skills/update-platform-docs/templates/practice-template.md similarity index 100% rename from plugins/agentic-docs/skills/platform/templates/practice-template.md rename to plugins/agentic-docs/skills/update-platform-docs/templates/practice-template.md