diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ebae08ed..79161afe 100644 --- a/.claude-plugin/marketplace.json +++ b/.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", diff --git a/plugins/repo-standards/.claude-plugin/plugin.json b/plugins/repo-standards/.claude-plugin/plugin.json new file mode 100644 index 00000000..5e9390b6 --- /dev/null +++ b/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" +} diff --git a/plugins/repo-standards/README.md b/plugins/repo-standards/README.md new file mode 100644 index 00000000..05567b15 --- /dev/null +++ b/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 +``` diff --git a/plugins/repo-standards/hooks/hooks.json b/plugins/repo-standards/hooks/hooks.json new file mode 100644 index 00000000..3389ccfb --- /dev/null +++ b/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..." + } + ] + } + ] + } +} diff --git a/plugins/repo-standards/references/laws/01-required-artifacts.md b/plugins/repo-standards/references/laws/01-required-artifacts.md new file mode 100644 index 00000000..c256da52 --- /dev/null +++ b/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. diff --git a/plugins/repo-standards/references/laws/02-contributing-template.md b/plugins/repo-standards/references/laws/02-contributing-template.md new file mode 100644 index 00000000..e1a6dc9b --- /dev/null +++ b/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 diff --git a/plugins/repo-standards/references/laws/03-agents-md-convention.md b/plugins/repo-standards/references/laws/03-agents-md-convention.md new file mode 100644 index 00000000..86537bea --- /dev/null +++ b/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) diff --git a/plugins/repo-standards/references/laws/04-coderabbit-config.md b/plugins/repo-standards/references/laws/04-coderabbit-config.md new file mode 100644 index 00000000..07991f28 --- /dev/null +++ b/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 diff --git a/plugins/repo-standards/references/laws/05-architecture-docs.md b/plugins/repo-standards/references/laws/05-architecture-docs.md new file mode 100644 index 00000000..9a09d6ce --- /dev/null +++ b/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?" diff --git a/plugins/repo-standards/references/laws/06-upstream-docs.md b/plugins/repo-standards/references/laws/06-upstream-docs.md new file mode 100644 index 00000000..d3b97487 --- /dev/null +++ b/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). diff --git a/plugins/repo-standards/references/laws/07-new-repo-mandate.md b/plugins/repo-standards/references/laws/07-new-repo-mandate.md new file mode 100644 index 00000000..e618c122 --- /dev/null +++ b/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. diff --git a/plugins/repo-standards/references/repo-standards-laws.md b/plugins/repo-standards/references/repo-standards-laws.md new file mode 100644 index 00000000..239d962a --- /dev/null +++ b/plugins/repo-standards/references/repo-standards-laws.md @@ -0,0 +1,25 @@ +# Repo Standards Laws + +Navigation index for repository agentic development standards. This file is **not normative** --- RFC 2119 language does not apply here. Rules live in `laws/`. + +## Agent Task Index + +Load only the law files your task requires. Do not read the entire `laws/` directory unless comprehensive coverage is explicitly needed. + +| Task | Load These Files | +|------|-----------------| +| Scaffold Repo | All files in `laws/` | +| Health Check | `laws/01-required-artifacts.md`, `laws/03-agents-md-convention.md`, `laws/04-coderabbit-config.md` | +| General Reference | All files in `laws/` | + +## Law Files + +| File | Topic | +|------|-------| +| [01-required-artifacts.md](laws/01-required-artifacts.md) | Required repo files and pass/fail criteria | +| [02-contributing-template.md](laws/02-contributing-template.md) | CONTRIBUTING.md template and required sections | +| [03-agents-md-convention.md](laws/03-agents-md-convention.md) | AGENTS.md convention, symlink policy, size limit | +| [04-coderabbit-config.md](laws/04-coderabbit-config.md) | .coderabbit.yaml configuration requirements | +| [05-architecture-docs.md](laws/05-architecture-docs.md) | Architecture documentation recommendations | +| [06-upstream-docs.md](laws/06-upstream-docs.md) | Upstream project documentation recommendations | +| [07-new-repo-mandate.md](laws/07-new-repo-mandate.md) | Post-April-2026 new repository mandate | diff --git a/plugins/repo-standards/scripts/check-agents-md-size.sh b/plugins/repo-standards/scripts/check-agents-md-size.sh new file mode 100755 index 00000000..c6d227fc --- /dev/null +++ b/plugins/repo-standards/scripts/check-agents-md-size.sh @@ -0,0 +1,50 @@ +#!/usr/bin/bash +# Check AGENTS.md (or CLAUDE.md) line count against 200-line limit +# SessionStart hook — outputs hookSpecificOutput JSON if over limit + +set -euo pipefail + +# Require jq for JSON parsing +if ! command -v jq &>/dev/null; then + echo "Error: jq is required but not installed. Install it with your package manager (e.g., 'sudo dnf install jq')." >&2 + exit 1 +fi + +# Read hook input +INPUT=$(cat) +CWD=$(echo "$INPUT" | jq -r '.cwd // empty') + +if [ -z "$CWD" ]; then + exit 0 +fi + +cd "$CWD" + +LINE_LIMIT=200 +TARGET="" + +if [ -f "AGENTS.md" ]; then + TARGET="AGENTS.md" +elif [ -f "CLAUDE.md" ]; then + TARGET="CLAUDE.md" +else + # No file to check + exit 0 +fi + +LINE_COUNT=$(wc -l < "$TARGET" | awk '{print $1}') + +if [ "$LINE_COUNT" -le "$LINE_LIMIT" ]; then + exit 0 +fi + +cat </dev/null; then + [ "$(yq e '.reviews.auto_review.enabled // .auto_review.enabled // false' "$CONFIG" 2>/dev/null)" = "true" ] && AUTO_REVIEW=true + yq e '.reviews.path_filters // .path_filters // ""' "$CONFIG" 2>/dev/null | grep -q "." && PATH_FILTERS=true + yq e '.reviews.instructions // .instructions // .reviews.review_instructions // ""' "$CONFIG" 2>/dev/null | grep -q "." && INSTRUCTIONS=true + else + grep -qE '^\s*enabled\s*:\s*true' "$CONFIG" 2>/dev/null && AUTO_REVIEW=true + grep -qE '^\s*(path_filters|path_instructions)\s*:' "$CONFIG" 2>/dev/null && PATH_FILTERS=true + grep -qE '^\s*(instructions|review_instructions)\s*:' "$CONFIG" 2>/dev/null && INSTRUCTIONS=true + fi +fi + +PASS=true +if [ "$EXISTS" = false ] || [ "$AUTO_REVIEW" = false ]; then + PASS=false +fi + +cat </dev/null; then + echo "Error: jq is required but not installed. Install it with your package manager (e.g., 'sudo dnf install jq')." >&2 + exit 1 +fi + +# Read hook input +INPUT=$(cat) +CWD=$(echo "$INPUT" | jq -r '.cwd // empty') + +if [ -z "$CWD" ]; then + exit 0 +fi + +cd "$CWD" + +# Track missing artifacts +declare -a MISSING=() + +# Required artifacts +[ ! -f "README.md" ] && MISSING+=("README.md") +[ ! -f "CONTRIBUTING.md" ] && MISSING+=("CONTRIBUTING.md") + +# AGENTS.md or CLAUDE.md (at least one must exist) +HAS_AGENTS=false +if [ -f "AGENTS.md" ] || [ -f "CLAUDE.md" ]; then + HAS_AGENTS=true +fi +[ "$HAS_AGENTS" = false ] && MISSING+=("AGENTS.md") + +# .coderabbit.yaml +[ ! -f ".coderabbit.yaml" ] && MISSING+=(".coderabbit.yaml") + +# Check CLAUDE.md symlink convention +SYMLINK_WARN="" +if [ -f "AGENTS.md" ] && [ -f "CLAUDE.md" ]; then + if [ ! -L "CLAUDE.md" ]; then + SYMLINK_WARN="CLAUDE.md exists but is not a symlink to AGENTS.md. Convention requires: ln -s AGENTS.md CLAUDE.md" + elif [ "$(readlink CLAUDE.md)" != "AGENTS.md" ]; then + SYMLINK_WARN="CLAUDE.md is a symlink but does not point to AGENTS.md (points to: $(readlink CLAUDE.md)). Convention requires: ln -sf AGENTS.md CLAUDE.md" + fi +elif [ -f "CLAUDE.md" ] && [ ! -f "AGENTS.md" ]; then + SYMLINK_WARN="CLAUDE.md exists without AGENTS.md. Convention requires AGENTS.md as the primary file with CLAUDE.md as a symlink." +fi + +# Exit silently if all present and no warnings +if [ ${#MISSING[@]} -eq 0 ] && [ -z "$SYMLINK_WARN" ]; then + exit 0 +fi + +# Build message +MSG="" +if [ ${#MISSING[@]} -gt 0 ]; then + ARTIFACT_LIST=$(printf '%s, ' "${MISSING[@]}" | sed 's/, $//') + MSG="MISSING REPO ARTIFACTS: The following required files are missing: ${ARTIFACT_LIST}." +fi + +if [ -n "$SYMLINK_WARN" ]; then + [ -n "$MSG" ] && MSG="${MSG} " + MSG="${MSG}SYMLINK WARNING: ${SYMLINK_WARN}" +fi + +MSG="${MSG} Run /repo-standards:scaffold-repo to generate missing artifacts." + +# Escape for JSON +MSG_ESCAPED=$(printf '%s' "$MSG" | sed 's/\\/\\\\/g; s/"/\\"/g') + +cat <"}' | bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-repo-artifacts.sh" +``` + +Parse the output. If JSON is returned, artifacts are missing. If no output, all required files exist. + +--- + +### Step 2: Run AGENTS.md Size Check + +```bash +echo '{"cwd":""}' | bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-agents-md-size.sh" +``` + +Parse the output. If JSON is returned, the file exceeds the 200-line limit. + +--- + +### Step 3: Run CodeRabbit Config Check + +```bash +bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-coderabbit-config.sh" "" +``` + +Parse the JSON output for `exists`, `auto_review`, `path_filters`, `instructions`, and `pass`. + +--- + +### Step 4: Additional Read-Based Checks + +Perform these checks by reading files directly: + +1. **CLAUDE.md symlink** --- use Bash to verify CLAUDE.md is a symlink pointing to AGENTS.md: `test -L CLAUDE.md && readlink CLAUDE.md` should return `AGENTS.md`. A regular file or a symlink to a different target is non-compliant. +2. **CONTRIBUTING.md sections** --- verify required section headers exist (case-insensitive match): Getting Started, Development Workflow, Branch Naming, Commit Messages, Testing, Code Review, Code Style +3. **docs/architecture.md** --- check if it exists (recommended, not required) +4. **docs/upstream.md** --- check if it exists (recommended, not required) + +--- + +### Step 5: Produce Report + +Output a compliance table: + +```text +| Check | Status | Detail | +|-------|--------|--------| +| README.md | PASS | Present | +| CONTRIBUTING.md | FAIL | Missing | +| AGENTS.md | PASS | Present, 142 lines | +| AGENTS.md size | PASS | 142 lines (limit: 200) | +| CLAUDE.md symlink | PASS | Symlink to AGENTS.md | +| .coderabbit.yaml | PASS | auto_review enabled | +| CodeRabbit path_filters | WARN | Not configured | +| CodeRabbit instructions | WARN | Not configured | +| docs/architecture.md | WARN | Not present (recommended) | +| docs/upstream.md | WARN | Not present (recommended) | +| CONTRIBUTING.md sections | FAIL | Missing: Branch Naming, Code Style | +``` + +Use these status levels: +- **PASS** --- meets the requirement +- **FAIL** --- required item missing or non-compliant +- **WARN** --- recommended item missing or non-optimal + +--- + +### Step 6: Offer Remediation + +If any FAIL items exist, offer to run `/repo-standards:scaffold-repo` to generate missing artifacts. + +If only WARN items exist, note them as recommendations but confirm the repository meets minimum compliance. diff --git a/plugins/repo-standards/skills/scaffold-repo/SKILL.md b/plugins/repo-standards/skills/scaffold-repo/SKILL.md new file mode 100644 index 00000000..fda26a36 --- /dev/null +++ b/plugins/repo-standards/skills/scaffold-repo/SKILL.md @@ -0,0 +1,109 @@ +--- +name: repo-standards:scaffold-repo +description: Use when setting up a new repository or bringing an existing repo into compliance with agentic development standards — scaffolds CONTRIBUTING.md, AGENTS.md, .coderabbit.yaml, and docs/architecture.md +user-invocable: true +allowed-tools: Read, Write, Bash, AskUserQuestion, Glob +argument-hint: "[target-directory]" +--- + +# Scaffold Repository + +You are scaffolding a repository to meet agentic development standards. All conventions come from the Repo Standards Laws. + +## User Arguments + +The user may provide a target directory: `$ARGUMENTS` + +If no directory is provided, use the current working directory. + +--- + +## Workflow + +### Step 0: Load Laws + +Read the laws index at `${CLAUDE_PLUGIN_ROOT}/references/repo-standards-laws.md`. Load all files listed under the "Scaffold Repo" task in the Agent Task Index. + +The Laws are authoritative. When this skill and the Laws conflict, the Laws win. + +--- + +### Step 1: Detect Current State + +Run the artifact check script to detect what exists and what is missing: + +```bash +echo '{"cwd":""}' | bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-repo-artifacts.sh" +``` + +If all artifacts pass, report compliance status to the user and exit. No further action needed. + +--- + +### Step 2: Gather Project Details + +Use `AskUserQuestion` to collect the following. Do not assume defaults for any of these: + +1. **Project name** --- human-readable name for the project +2. **Primary language** --- Go, Python, Shell, etc. +3. **Team name** --- team that owns this repository +4. **Multiple components** --- does this repository contain multiple components? (y/n) +5. **Upstream relationship** --- does this repo interact with an upstream project? (y/n) +6. **Brief project description** --- 2--3 sentences describing what the project does + +--- + +### Step 3: Generate Missing Artifacts + +For each missing artifact, generate the file using templates from the Laws and customize with the gathered project details. + +#### CONTRIBUTING.md (if missing) +- Use the template structure from Law 02 +- Fill in language-specific tooling (formatters, test commands) based on the primary language +- Include all required sections + +#### AGENTS.md (if missing) +- Follow Law 03 conventions +- Include: project overview, build/test/lint commands, code style, PR/commit format, security considerations +- Keep under 200 lines + +#### .coderabbit.yaml (if missing) +- Follow Law 04 requirements +- Enable auto_review +- Add path_filters appropriate for the project language +- Include basic review instructions + +#### docs/architecture.md (if missing and multiple components confirmed) +- Follow Law 05 recommendations +- Create a skeleton with section headers for the team to fill in + +#### docs/upstream.md (if missing and upstream relationship confirmed) +- Follow Law 06 recommendations +- Create a skeleton with section headers for the team to fill in + +--- + +### Step 4: Create CLAUDE.md Symlink + +If CLAUDE.md does not exist or is not a symlink to AGENTS.md, and AGENTS.md exists (either pre-existing or generated in Step 3): + +```bash +if [ -f AGENTS.md ]; then + ln -sf AGENTS.md CLAUDE.md +fi +``` + +If AGENTS.md does not exist, do NOT create the symlink. Report that AGENTS.md must be created first. + +--- + +### Step 5: Summary + +Report to the user: +- Files created (list each with path) +- Files that already existed (skipped) +- Remaining manual steps: + - Fill in skeleton sections in docs/architecture.md and docs/upstream.md (if created) + - Register with Cyborg program (if applicable) + - Configure OpenShift Test Extensions (if applicable) + - Review generated AGENTS.md and customize for project specifics