Repo Conventions Checker

Walk a Git repository and surface drift from widely accepted open-source conventions. The output is a markdown punch-list grouped by severity, with file paths and one-line fix suggestions. Designed to be runnable in a CI job (exit non-zero on severity: blocker) or invoked ad-hoc by a human auditor.

What this skill checks

The skill grades a repo against four buckets. Each rule produces zero or more findings; each finding has file, severity (blocker / warning / suggestion), and fix.

1. Top-level files

2. CI / automation

• .github/workflows/*.yml exists with at least one push or pull_request trigger. Severity: warning if missing.
• A workflow runs lint AND test (look for npm test / pnpm test / pytest / cargo test / go test shell tokens). Severity: warning if either is absent.
• Dependabot / Renovate config (.github/dependabot.yml or renovate.json). Severity: suggestion.

3. PR / issue ergonomics

• .github/PULL_REQUEST_TEMPLATE.md. Severity: suggestion.
• .github/ISSUE_TEMPLATE/ directory or single template. Severity: suggestion.

4. README quality

• README has a "Getting started" or "Install" section (regex match on the first 200 lines). Severity: warning.
• README has at least one code fence (```). Severity: warning.
• README mentions the project name in the # Title heading. Severity: suggestion.

Inputs

• repo_dir: absolute path to the checkout (assumed clean, on default branch).
• target_branch (optional): defaults to main. Used only if the skill needs to compare against origin/<target_branch> for changelog hints.

Output shape

A single markdown report with this structure:

# Conventions audit · <repo-name>

**Verdict:** <pass | warning | block>
**Findings:** <N> (<blockers>, <warnings>, <suggestions>)

## Blockers
- `<file>` — <one-line fix>

## Warnings
- `<file>` — <one-line fix>

## Suggestions
- `<file>` — <one-line fix>

A non-zero exit on blockers > 0 is a sane CI default; teams can flip it via an env var.

Execution recipe

The skill is a playbook for an LLM-driven agent. The agent should:

1. Inventory the working directory with ls -la at the repo root and inside .github/. Note presence/absence of every file in the tables above.
2. Read README.md (first 500 lines). Apply the regex/structure checks. Flag findings.
3. Inventory CI with ls .github/workflows/ and read each .yml. Look for lint/test shell tokens.
4. Inventory PR/issue templates with a recursive ls of .github/.
5. Compose the report in the schema above. Sort findings within each severity by file path, ascending.
6. Verify by re-running step 1 and re-counting top-level files; the counts in the report must match the directory listing.

Verification step (always do this last)

After producing the report, re-list the repo top-level and the .github/ directory. Diff your reported "missing" files against the actual listing. If any "missing" file actually exists, regenerate the report — a false-positive on a missing LICENSE is worse than reporting nothing, because it makes the whole report distrustable.

What this skill is NOT

• Not a security scanner. Use gitleaks / semgrep / a dedicated SCA tool for vulnerabilities and secrets. The intersection here (e.g., committed .env files) is the only overlap we report.
• Not a code reviewer. It looks at presence + structure of meta files, not at the source code's correctness.
• Not a license checker. LICENSE presence is checked; the SPDX id vs. project goals (e.g., GPL inside a permissive product) is out of scope. Pair with the amitte/license-classifier agent for that.

Example invocation

# As a CI gate
amitte invoke amitte/repo-conventions-checker \
  --input '{"repo_dir":"'"$GITHUB_WORKSPACE"'"}' \
  --fail-on blocker

# Ad-hoc audit
amitte invoke amitte/repo-conventions-checker \
  --input '{"repo_dir":"./my-repo"}' > audit.md

Tuning notes

• For monorepos: pass the package directory as repo_dir to scope the audit. The skill does NOT walk into subpackages by default (no recursion); it audits one project at a time.
• For private repos: nothing in the skill leaves the local machine — it's all ls + cat against repo_dir. Safe to run on air-gapped checkouts.