OCPEDGE-2575: Add repo-standards plugin with hooks and compliance skills

.claude-plugin/marketplace.json

@@ -60,6 +60,12 @@
       "description": "Post-review utilities for PR workflows — vet findings, triage CodeRabbit reviews, filter noise",
       "version": "1.1.0"
     },
+    {
+      "name": "repo-standards",
+      "source": "./plugins/repo-standards",
+      "description": "Repository compliance checking and scaffolding for agentic development standards",
+      "version": "1.0.0"
+    },
     {
       "name": "two-node",
       "source": "./plugins/two-node",

plugins/repo-standards/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "repo-standards",
+  "description": "Repository compliance checking and scaffolding for agentic development standards",
+  "version": "1.0.0",
+  "author": { "name": "jeff-roche" },
+  "homepage": "https://github.com/openshift-eng/edge-tooling",
+  "license": "Apache-2.0"
+}

plugins/repo-standards/README.md

@@ -0,0 +1,44 @@
+# repo-standards
+
+Repository compliance checking and scaffolding for agentic development standards.
+
+## What It Does
+
+Enforces a baseline set of repository artifacts and conventions that enable effective AI-assisted development. Checks run automatically at session start and surface missing or non-compliant files.
+
+## Automatic Hooks (SessionStart)
+
+Two hooks fire when a Claude Code session begins:
+
+- **check-repo-artifacts** --- detects missing required files (README.md, CONTRIBUTING.md, AGENTS.md, .coderabbit.yaml) and warns if CLAUDE.md is not a symlink to AGENTS.md
+- **check-agents-md-size** --- warns if AGENTS.md exceeds the 200-line limit
+
+No action is taken automatically. Hooks report findings and suggest next steps.
+
+## Skills
+
+### `/repo-standards:scaffold-repo [directory]`
+
+Interactive scaffolding for new or non-compliant repositories. Gathers project details, generates missing artifacts from templates, and creates the CLAUDE.md symlink.
+
+### `/repo-standards:health-check [directory]`
+
+Full compliance audit. Runs all checks (artifacts, AGENTS.md size, CodeRabbit config quality, CONTRIBUTING.md sections, architecture docs) and produces a pass/warn/fail report table.
+
+## Laws
+
+Policy content lives in `references/laws/`. Seven law files cover:
+
+1. Required artifacts and pass/fail criteria
+2. CONTRIBUTING.md template and required sections
+3. AGENTS.md convention (vendor-neutral standard, symlink, size limit)
+4. CodeRabbit configuration requirements
+5. Architecture documentation recommendations
+6. Upstream project documentation recommendations
+7. New repository mandate (post-April 2026)
+
+## Installation
+
+```bash
+/plugin marketplace add openshift-eng/edge-tooling repo-standards
+```

plugins/repo-standards/hooks/hooks.json

@@ -0,0 +1,23 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-repo-artifacts.sh",
+            "timeout": 10,
+            "statusMessage": "Checking repo standards compliance..."
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-agents-md-size.sh",
+            "timeout": 5,
+            "statusMessage": "Checking AGENTS.md size..."
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/repo-standards/references/laws/01-required-artifacts.md

@@ -0,0 +1,27 @@
+# Law 01: Required Artifacts
+
+Every repository MUST contain the following files at the repository root.
+
+## Required Files
+
+| File | Purpose | Pass Criteria |
+|------|---------|---------------|
+| `README.md` | Foundational project context | File exists and is non-empty |
+| `CONTRIBUTING.md` | Contribution conventions and workflows | File exists, contains required sections (see Law 02) |
+| `AGENTS.md` | AI-specific guidance for agentic tools | File exists, under 200 lines (see Law 03) |
+| `.coderabbit.yaml` | AI code review configuration | File exists, has `auto_review` enabled (see Law 04) |
+
+## Recommended Files
+
+| File | Purpose | When Applicable |
+|------|---------|-----------------|
+| `docs/architecture.md` | System design and component boundaries | Repos with multiple components (see Law 05) |
+| `docs/upstream.md` | Upstream project relationship | Repos interacting with upstream projects (see Law 06) |
+| OpenShift Test Extensions config | CI test configuration | Repos with OpenShift CI jobs |
+| Cyborg team/repo data | Team metadata for AI tooling | Repos enrolled in Cyborg program |
+
+## Pass/Fail
+
+A repository PASSES the required artifacts check when all four Required files exist and meet their individual pass criteria. Missing any Required file is a FAIL.
+
+Recommended files do not affect pass/fail status but are surfaced as warnings during health checks.

plugins/repo-standards/references/laws/02-contributing-template.md

@@ -0,0 +1,75 @@
+# Law 02: CONTRIBUTING.md Template
+
+Every repository MUST have a `CONTRIBUTING.md` with the sections below. Adapt content to your project; the section structure is mandatory.
+
+## Required Sections
+
+### Getting Started
+
+MUST cover:
+- Prerequisites (languages, tools, accounts)
+- Repository setup steps
+- First build / first test command
+
+### Development Workflow
+
+MUST describe the standard flow:
+1. Branch from `main`
+2. Make changes
+3. Run tests locally
+4. Open a pull request
+5. Pass code review
+6. Merge
+
+### Branch Naming
+
+SHOULD use the pattern: `type/short-description`
+
+This convention is configurable per repository. Override via repository-specific branch protection rules or CONTRIBUTING.md customization.
+
+Valid types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`
+
+### Commit Messages
+
+MUST use conventional commits: `type(scope): description`
+
+Examples:
+- `feat(api): add batch endpoint`
+- `fix(controller): prevent nil pointer in reconcile loop`
+- `docs(readme): update deployment instructions`
+- `refactor(store): extract cache layer`
+- `test(e2e): add upgrade path coverage`
+- `chore(deps): bump Go to 1.23`
+
+Valid types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+### Testing
+
+MUST cover:
+- Unit tests required for new code
+- Integration tests required for API changes
+- How to run tests (e.g., `make test`)
+- Minimum coverage target: 80%
+
+### Code Review
+
+MUST state:
+- Minimum 1 approval required
+- CI MUST pass before merge
+
+### Code Style
+
+MUST reference:
+- Language-specific formatters (e.g., `gofmt`, `black`, `prettier`)
+- Format command (e.g., `make fmt`)
+
+## Validation Checklist
+
+Health checks validate CONTRIBUTING.md contains these section headers (case-insensitive):
+- [ ] Getting Started
+- [ ] Development Workflow
+- [ ] Branch Naming
+- [ ] Commit Messages
+- [ ] Testing
+- [ ] Code Review
+- [ ] Code Style

plugins/repo-standards/references/laws/03-agents-md-convention.md

@@ -0,0 +1,42 @@
+# Law 03: AGENTS.md Convention
+
+## Standard
+
+AGENTS.md is the vendor-neutral AI agent instruction standard. Originally released by OpenAI in August 2025, it was contributed to the Agentic AI Foundation (a directed fund under the Linux Foundation) in December 2025. See the [supported tools list](https://github.com/agentsmd/agents.md#supported-tools) for current tool coverage.
+
+Every repository MUST use `AGENTS.md` as the primary agent instruction file.
+
+## Symlink Policy
+
+`CLAUDE.md` MUST be a symlink to `AGENTS.md`:
+
+```bash
+ln -s AGENTS.md CLAUDE.md
+```
+
+Do NOT maintain separate files. Do NOT copy content between them. The symlink ensures all tools read identical instructions.
+
+## Size Limit
+
+AGENTS.md MUST be under 200 lines.
+
+Large instruction files degrade AI performance --- models spend context on boilerplate instead of your code. Use just-in-time data loading for detailed context:
+- Reference files (`references/`) for lookup tables and detailed specs
+- Skill files for workflow-specific instructions
+- Inline comments in code for local context
+
+## Required Content
+
+AGENTS.md MUST contain:
+- **Project overview** --- what the project does, in 2--3 sentences
+- **Build/test/lint commands** --- exact commands to build, test, and lint
+- **Code style** --- formatter, linter, naming conventions
+- **PR/commit format** --- branch naming, commit message conventions
+- **Security considerations** --- secrets handling, auth patterns, sensitive paths
+
+## Anti-Patterns
+
+- Pasting entire style guides into AGENTS.md
+- Duplicating README content
+- Including environment-specific setup (use .env or local config)
+- Embedding large lookup tables (use reference files instead)

plugins/repo-standards/references/laws/04-coderabbit-config.md

@@ -0,0 +1,56 @@
+# Law 04: CodeRabbit Configuration
+
+## Required
+
+`.coderabbit.yaml` MUST exist at the repository root.
+
+`.coderabbit.yaml` MUST have an `auto_review` section with reviews enabled:
+
+```yaml
+reviews:
+  auto_review:
+    enabled: true
+```
+
+## Recommended
+
+### Path Filters
+
+SHOULD exclude non-code paths from review:
+
+```yaml
+reviews:
+  path_filters:
+    - "!docs/**"
+    - "!vendor/**"
+    - "!**/testdata/**"
+    - "!CHANGELOG.md"
+```
+
+### Instructions
+
+SHOULD include project-specific review rules:
+
+```yaml
+reviews:
+  instructions: |
+    Focus on error handling, security, and API compatibility.
+    Flag any hardcoded credentials or secrets.
+    Verify unit test coverage for new functions.
+```
+
+### Static Analysis Tools
+
+SHOULD reference valid static analysis tools appropriate for the project language:
+
+- Go: `golangci-lint`
+- Shell: `shellcheck`
+- Python: `ruff`, `mypy`
+- YAML: `yamllint`
+- Dockerfile: `hadolint`
+
+## Pass/Fail
+
+- PASS: `.coderabbit.yaml` exists and `auto_review` is enabled
+- WARN: Missing `path_filters` or `instructions`
+- FAIL: File missing or `auto_review` not configured

plugins/repo-standards/references/laws/05-architecture-docs.md

@@ -0,0 +1,32 @@
+# Law 05: Architecture Documentation
+
+## Applicability
+
+Repositories with multiple components or non-trivial system boundaries SHOULD have a `docs/architecture.md`.
+
+## Content
+
+`docs/architecture.md` SHOULD cover:
+
+- **System overview** --- high-level description of what the system does and how components relate
+- **Key design decisions** --- ADRs (Architecture Decision Records) or inline rationale for non-obvious choices
+- **Component boundaries** --- what each component owns, what it delegates
+- **Data flow** --- how data moves through the system, key interfaces
+- **Dependencies** --- external services, libraries, APIs the system relies on
+- **Constraints** --- performance budgets, compatibility requirements, deployment limitations
+- **Anti-patterns** --- known bad approaches and why they were rejected
+
+## Why This Matters
+
+Without architecture documentation, AI agents optimize locally. They produce correct code that violates system-level invariants:
+
+- Adding direct database access in a component that should go through an API layer
+- Duplicating logic that belongs in a shared library
+- Breaking event ordering guarantees
+- Introducing circular dependencies
+
+Architecture docs are guardrails. They prevent AI from making changes that are locally correct but globally wrong.
+
+## Format
+
+No prescribed format. ADR logs, C4 diagrams, or plain prose all work. The key requirement is that an AI agent reading the file can answer: "What constraints exist that I cannot infer from the code alone?"

plugins/repo-standards/references/laws/06-upstream-docs.md

@@ -0,0 +1,30 @@
+# Law 06: Upstream Documentation
+
+## Applicability
+
+Repositories that interact with upstream open-source projects SHOULD have a `docs/upstream.md`.
+
+## Content
+
+`docs/upstream.md` SHOULD cover:
+
+- **Upstream project** --- name, repository URL, communication channels (mailing list, Slack, IRC)
+- **Relationship** --- one of: consumer, contributor, maintainer, fork
+- **Contribution process** --- how to submit patches upstream, CLA requirements, review expectations
+- **Carry patches** --- list of patches carried downstream, rationale, upstream tracking issues
+- **Sync cadence** --- how often the downstream syncs with upstream (e.g., every release, weekly rebase)
+- **Style differences** --- where downstream conventions differ from upstream (naming, formatting, testing)
+
+## Why This Matters
+
+AI agents lack institutional knowledge about upstream relationships. Without this documentation, agents may:
+
+- Submit PRs that conflict with upstream conventions
+- Duplicate work already done upstream
+- Modify carry patches without understanding why they exist
+- Generate code in the wrong style for upstream contribution
+- Miss required CLA or sign-off steps
+
+## Format
+
+Plain markdown. Keep it factual. Update when the relationship changes (e.g., fork becomes contributor, sync cadence changes).

plugins/repo-standards/references/laws/07-new-repo-mandate.md

@@ -0,0 +1,32 @@
+# Law 07: New Repository Mandate
+
+## Effective Date
+
+April 1, 2026.
+
+## Policy
+
+All repositories created after the effective date are presumed 100% agentic. AI agents are expected participants in the development workflow, not optional add-ons.
+
+## Requirements
+
+New repositories MUST have from day one:
+
+- All Required artifacts (Law 01): README.md, CONTRIBUTING.md, AGENTS.md, .coderabbit.yaml
+- AGENTS.md with CLAUDE.md symlink (Law 03)
+- Architecture documentation if the repo has multiple components (Law 05)
+- Upstream documentation if the repo interacts with upstream projects (Law 06)
+
+## No Grandfathering
+
+New repositories receive no grace period. The full standard applies immediately at repository creation.
+
+Do not plan to "add AGENTS.md later" or "set up CodeRabbit after launch." These artifacts are part of the repository scaffold, alongside LICENSE and .gitignore.
+
+## Rationale
+
+Retrofitting agentic standards is expensive. Teams spend hours reconstructing context that should have been captured at creation time. Starting with the full standard costs minutes; adding it later costs days.
+
+## Enforcement
+
+The `repo-standards` plugin SessionStart hooks automatically detect missing artifacts. The `/repo-standards:scaffold-repo` skill generates compliant scaffolding for new repositories.