Add contributor docs, CI validation, and repo hygiene

[marty916]

Summary

Repository hygiene and contributor-onboarding pass. No changes to the govkit plugin or skill content.

• Fix README install commands. marketplace.json names the marketplace aipos, but the README told users to run govkit@accelerated-innovation / marketplace update accelerated-innovation, which would not resolve. Aligned both commands to aipos. Also added a Contributing section.
• Add CONTRIBUTING.md. Short, repo-specific guide: layout, how to add a skill (via the template), a pre-PR checklist (claude plugin validate ., JSON validity, version bump), the CI note, and MIT licensing of contributions.
• Add CI workflow (.github/workflows/validate.yml). Runs claude plugin validate . on every PR and on pushes to main. Installs @anthropic-ai/claude-code on Node 22. Structural validation only — no API key / secret, so it also works for fork PRs. Includes a concurrency group to cancel superseded runs.
• Add .gitignore for OS/editor/Node/local-Claude cruft. Scoped the Claude rule to .claude/ so it does not catch the committed .claude-plugin/ directory (verified with git check-ignore).

Notes

• If aipos was itself an unintended marketplace name, the alternative fix is to rename marketplace.json's name to accelerated-innovation instead — happy to flip that direction.
• Anthropic's docs strongly indicate plugin validate needs no auth or interactive onboarding in CI but don't state it verbatim; this PR's own CI run is the end-to-end confirmation.

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

Add contributor docs and CI validation for Claude plugin marketplace

📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Fix README marketplace install/update commands to match the actual marketplace name.
• Add CONTRIBUTING guide for skill authoring, validation, and PR expectations.
• Add GitHub Actions workflow to run claude plugin validate . on PRs and main pushes.

Diagram

graph TD
  Dev["Contributor"] --> Docs["Docs (README/CONTRIBUTING)"]
  Dev --> PR["Pull request"] --> GHA["GitHub Actions"] --> Validate["claude plugin validate"] --> Status["Required check"]
  Validate --> Manifests["Plugin manifests"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Pin `@anthropic-ai/claude-code` to a specific version

• ➕ Avoids unexpected CI breaks from upstream CLI releases
• ➕ Improves reproducibility across PRs and time
• ➖ Requires periodic maintenance/version bumps to pick up fixes and new validations

2. Use `npx @anthropic-ai/claude-code` (optionally with npm cache)

• ➕ Avoids global installs and keeps the workflow more ephemeral
• ➕ Can be combined with caching to speed up repeated runs
• ➖ Still depends on npm registry availability at runtime
• ➖ If unpinned, still susceptible to upstream breaking changes

Recommendation: The PR’s approach (run claude plugin validate . in GitHub Actions without secrets) is the right baseline because it uses the authoritative validator and works for fork PRs. Consider additionally pinning the @anthropic-ai/claude-code version to improve CI determinism; npx vs global install is a secondary preference.

Files changed (4) +87 / -2

Documentation (2) +55 / -2

CONTRIBUTING.mdAdd repository-specific contribution and skill-authoring guide +49/-0

Add repository-specific contribution and skill-authoring guide

• Adds a contributor guide describing repo layout, how to add/change skills, and a pre-PR validation checklist. Documents CI expectations and clarifies that contributions are MIT-licensed.

CONTRIBUTING.md

README.mdFix marketplace name in install/update commands and link to contributing docs +6/-2

Fix marketplace name in install/update commands and link to contributing docs

• Corrects the marketplace identifier used in the '/plugin install' and '/plugin marketplace update' examples to match 'marketplace.json' ('aipos'). Adds a Contributing section pointing to CONTRIBUTING.md and noting CI validation.

README.md

Other (2) +32 / -0

validate.ymlAdd CI job running 'claude plugin validate' on PRs and main +32/-0

Add CI job running 'claude plugin validate' on PRs and main

• Introduces a GitHub Actions workflow triggered on pull requests and pushes to 'main'. Installs Node 22 and the Claude Code CLI, then runs 'claude plugin validate .' with concurrency cancellation to avoid redundant runs.

.github/workflows/validate.yml

.gitignoreIgnore OS/editor/Node and local Claude Code artifacts +0/-0

Ignore OS/editor/Node and local Claude Code artifacts

• Adds ignore rules for common OS/editor files, Node tooling artifacts, environment files, and local Claude Code project settings. Ensures local '.claude/' is ignored without excluding the committed '.claude-plugin/' directory.

.gitignore

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Unpinned CI tool versions ✓ Resolved 🐞 Bug ⛨ Security

Description

The CI workflow installs floating versions of GitHub Actions (major tags) and the Claude Code CLI
(latest from npm), making validation results non-reproducible and increasing supply-chain exposure
if upstream tags/releases change. This can lead to sudden CI breakages or unexpected behavior
without any repo changes.

Code

.github/workflows/validate.yml[R18-27]

+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/claude-code

Evidence

The workflow installs dependencies using tags/latest rather than pinned versions, as shown by the
uses: ...@v4 steps and the unversioned global npm install.

.github/workflows/validate.yml[18-27]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The workflow uses version ranges / moving targets:
- `actions/checkout@v4` and `actions/setup-node@v4` (major tag)
- `npm install -g @anthropic-ai/claude-code` (implicit latest)

This makes CI behavior drift over time.

## Issue Context
This job is intended to be a deterministic structural validation gate (`claude plugin validate .`).

## Fix Focus Areas
- .github/workflows/validate.yml[18-32]

## Suggested fix
- Pin `@anthropic-ai/claude-code` to a specific version (e.g. `npm install -g @anthropic-ai/claude-code@<known-good>`).
- If you want stronger supply-chain hardening, pin GitHub Actions to a commit SHA (optionally keeping the major tag as a comment for readability).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. No workflow permissions set ✓ Resolved 🐞 Bug ⛨ Security

Description

The workflow does not declare an explicit permissions: block, so it relies on repository/org
defaults for the GITHUB_TOKEN, which may grant broader access than this read-only validation job
needs. This makes the workflow’s security posture less explicit and harder to audit.

Code

.github/workflows/validate.yml[R1-17]

+name: Validate plugin
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Cancel superseded runs on the same ref (e.g. rapid pushes to a PR branch).
+concurrency:
+  group: validate-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: claude plugin validate
+    runs-on: ubuntu-latest
+    steps:

Evidence

The file defines on:, concurrency:, and jobs: but contains no permissions: key at either
workflow or job scope.

.github/workflows/validate.yml[1-17]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The workflow lacks an explicit `permissions:` section, so token permissions depend on defaults rather than being least-privilege by construction.

## Issue Context
This workflow only checks out code and runs local validation; it should not need write permissions.

## Fix Focus Areas
- .github/workflows/validate.yml[1-17]

## Suggested fix
Add a top-level permissions block such as:
```yml
permissions:
 contents: read
```
(Or the minimal set required by your checkout/setup steps if additional scopes are needed.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---