Merge pull request #64 from stbenjam/linter

Use claudelint to verify our plugins and marketplace adhere to standards

Author: openshift-merge-bot[bot]

.claude-plugin/marketplace.json

@@ -48,6 +48,16 @@
       "name": "agendas",
       "source": "./plugins/agendas",
       "description": "A plugin to create various meeting agendas"
+    },
+    {
+      "name": "openshift",
+      "source": "./plugins/openshift",
+      "description": "OpenShift development utilities and helpers"
+    },
+    {
+      "name": "yaml",
+      "source": "./plugins/yaml",
+      "description": "YAML documentation and utilities"
     }
   ]
 }

.claudelint.yaml

@@ -0,0 +1,66 @@
+# claudelint configuration for ai-helpers marketplace
+# https://github.com/stbenjam/claudelint
+
+rules:
+  # Plugin structure rules
+  plugin-json-required:
+    enabled: true
+    severity: error
+  
+  plugin-json-valid:
+    enabled: true
+    severity: error
+  
+  plugin-naming:
+    enabled: true
+    severity: warning
+  
+  commands-dir-required:
+    enabled: false  # Plugins can have just skills or hooks
+    severity: warning
+  
+  commands-exist:
+    enabled: false  # Plugins can have just skills or hooks
+    severity: info
+  
+  plugin-readme:
+    enabled: true
+    severity: warning
+  
+  # Command format rules
+  command-naming:
+    enabled: true
+    severity: warning
+  
+  command-frontmatter:
+    enabled: true
+    severity: error
+  
+  command-sections:
+    enabled: true
+    severity: warning
+  
+  command-name-format:
+    enabled: true
+    severity: warning
+  
+  # Marketplace rules
+  marketplace-json-valid:
+    enabled: auto
+    severity: error
+  
+  marketplace-registration:
+    enabled: auto
+    severity: error
+  
+  # Skills rules
+  skill-frontmatter:
+    enabled: true
+    severity: warning
+
+# Exclude patterns
+exclude: []
+
+# Treat warnings as errors in CI
+strict: false
+

.github/workflows/lint-plugins.yml

@@ -0,0 +1,56 @@
+name: Lint Plugins
+
+on:
+  pull_request:
+    paths:
+      - 'plugins/**'
+      - '.claude-plugin/**'
+      - '.github/workflows/lint-plugins.yml'
+  push:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Pull claudelint Docker image
+        run: docker pull ghcr.io/stbenjam/claudelint:main
+      
+      - name: Run claudelint
+        run: |
+          docker run --rm \
+            -v ${{ github.workspace }}:/workspace \
+            -w /workspace \
+            ghcr.io/stbenjam/claudelint:main \
+            -v --strict
+      
+      - name: Comment on PR (on failure)
+        if: failure() && github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const output = `⚠️ Plugin linter found issues.
+            
+            Run locally to see details:
+            \`\`\`bash
+            docker run --rm -v $(pwd):/workspace ghcr.io/stbenjam/claudelint:main
+            \`\`\`
+            
+            Or install and run directly:
+            \`\`\`bash
+            pip install claudelint
+            claudelint
+            \`\`\`
+            `;
+            
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: output
+            });

AGENTS.md

@@ -271,6 +271,20 @@ If your command needs helper scripts (Python, Bash, etc.):
 
 **Example:** `plugins/prow-job/skills/prow-job-analyze-resource/parse_all_logs.py`
 
+### Validating with the Linter
+
+Before committing changes, always run the plugin linter to ensure compliance:
+
+```bash
+make lint
+```
+
+**When to run the linter:**
+- After creating a new plugin
+- After adding or modifying commands
+- Before committing changes
+- To diagnose structural issues
+
 ## Best Practices for AI Agents
 
 ### When Implementing Commands
@@ -281,6 +295,7 @@ If your command needs helper scripts (Python, Bash, etc.):
 4. **Include error handling:** Document failure scenarios and recovery
 5. **Add examples:** Show common usage patterns
 6. **Test before committing:** Verify the command works as expected
+7. **Run the linter:** Use `make lint` to validate your plugin structure and format
 
 ### When Writing SKILL.md Files
 

Makefile

@@ -0,0 +1,25 @@
+# Makefile for ai-helpers
+
+# Container runtime (podman or docker)
+CONTAINER_RUNTIME ?= $(shell command -v podman 2>/dev/null || echo docker)
+
+# claudelint image
+CLAUDELINT_IMAGE = ghcr.io/stbenjam/claudelint:main
+
+.PHONY: help
+help: ## Show this help message
+	@echo "Available targets:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: lint
+lint: ## Run plugin linter (verbose, strict mode)
+	@echo "Running claudelint with $(CONTAINER_RUNTIME)..."
+	$(CONTAINER_RUNTIME) run --rm -v $(PWD):/workspace:Z ghcr.io/stbenjam/claudelint:main -v --strict
+
+.PHONY: lint-pull
+lint-pull: ## Pull the latest claudelint image
+	@echo "Pulling latest claudelint image..."
+	$(CONTAINER_RUNTIME) pull $(CLAUDELINT_IMAGE)
+
+.DEFAULT_GOAL := help
+

README.md

@@ -135,6 +135,19 @@ If you're contributing several related commands that warrant their own plugin:
    ```
 3. Register your plugin in `.claude-plugin/marketplace.json`
 
+### Validating Plugins
+
+This repository uses [claudelint](https://github.com/stbenjam/claudelint) to validate plugin structure:
+
+```bash
+make lint
+```
+
+## Additional Documentation
+
+- **[AGENTS.md](AGENTS.md)** - Complete guide for AI agents working with this repository
+- **[CLAUDE.md](CLAUDE.md)** - Claude-specific configuration and notes
+
 ## License
 
 See [LICENSE](LICENSE) for details.

plugins/ci/commands/ask-sippy.md

@@ -4,7 +4,7 @@ argument-hint: [question]
 ---
 
 ## Name
-ask-sippy
+ci:ask-sippy
 
 ## Synopsis
 ```

plugins/ci/commands/query-job-status.md

@@ -4,7 +4,7 @@ argument-hint: <execution-id>
 ---
 
 ## Name
-query-job-status
+ci:query-job-status
 
 ## Synopsis
 ```

plugins/ci/commands/trigger-periodic.md

@@ -4,7 +4,7 @@ argument-hint: <job-name> [ENV_VAR=value ...]
 ---
 
 ## Name
-trigger-periodic
+ci:trigger-periodic
 
 ## Synopsis
 ```

plugins/ci/commands/trigger-postsubmit.md

@@ -4,7 +4,7 @@ argument-hint: <job-name> <org> <repo> <base-ref> <base-sha> [ENV_VAR=value ...]
 ---
 
 ## Name
-trigger-postsubmit
+ci:trigger-postsubmit
 
 ## Synopsis
 ```