Audit Plugin

Project: !basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $PWD

Branch: !git branch --show-current 2>/dev/null || echo "unknown"

Reviews the Claude Code addon in the current project (plugin, skill, sub-agent, or a combination)

against official Claude Code best practices. Generates actionable GitHub issues and a prioritised

fix plan.

Step 0: Pre-flight check

gh auth status 2>&1 || { echo "ERROR: gh is not authenticated. Run: gh auth login"; exit 1; }

Step 1: Identify what kind of addon this project defines

Scan for known Claude Code addon files:

find . -not -path './.git/*' \( \
  -name 'plugin.json' -path '*/.claude-plugin/*' \
  -o -name 'SKILL.md' -path '*/skills/*' \
  -o -name '*.md' -path '*/agents/*' \
\) 2>/dev/null

Read each file found. Build a mental model of:

• Plugin manifest (.claude-plugin/plugin.json) — name, version, declared agents/skills
• Skills (skills//SKILL.md) — frontmatter fields, body structure, tool declarations
• Agents (agents/.md) — frontmatter fields, description examples, tool restrictions

Step 2: Fetch current best-practice documentation

Use WebFetch to retrieve up-to-date guidance from these known URLs:

• Skills: https://code.claude.com/docs/en/skills
• Sub-agents: https://code.claude.com/docs/en/agents
• Plugins: https://code.claude.com/docs/en/plugins

If any URL returns an error, use WebSearch to find the current equivalent under code.claude.com.

Summarise the key quality criteria from each source.

Step 3: Evaluate against best practices

For plugin.json, check:

• Required fields present: name, version, description, author, license
• minVersion set to a current compatible value
• Keywords are relevant and searchable
• description is concise and accurate

For each SKILL.md, check:

• description is a single unbroken line under 1,536 characters (combined with whentouse)
• allowed-tools is set and follows least-privilege (only tools the skill actually needs)
• Body is under 500 lines; large reference content moved to separate files
• Shell injection blocks (` !command `) are used where live context would help
• Step numbering is clear and actionable
• Code blocks specify a language
• Prose lines are ≤ 120 characters

Audit Standards

Project: !basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $PWD

Branch: !git branch --show-current 2>/dev/null || echo "unknown"

Audits the current project against the personal development standards loaded from ~/.claude/CLAUDE.md.

Generates actionable GitHub issues and a prioritised fix plan.

The development standards from the user's global ~/.claude/CLAUDE.md are already loaded into context.

The key principles to audit against are:

1. Codify, Don't Document — manual steps should be executable scripts
2. Bash Script UX with pfb — terminal output uses pfb with correct visual hierarchy
3. Markdown Standards — all markdown passes markdownlint with zero warnings
4. Professional Documentation Tone — formal docs are objective, not personal
5. Version Control Everything — correct files committed, secrets excluded
6. Fail Fast, Pivot Early — (process principle, skip for static audit)
7. Behavioral Integrity — (process principle, skip for static audit)

Step 0: Pre-flight check

gh auth status 2>&1 || { echo "ERROR: gh is not authenticated. Run: gh auth login"; exit 1; }

Step 1: Inventory the project

find . -not -path './.git/*' -type f | sort

Also read:

• README.md — documentation tone and completeness
• CLAUDE.md — project AI context file exists and is current
• Any .env, .env.template, .gitignore — secrets handling
• Any *.sh files — bash scripting standards
• Any *.md files — markdown quality

Step 2: Audit each principle

Principle 1 — Codify, Don't Document

• Does the README describe manual steps that should instead be scripts?
• Do bash scripts use #!/usr/bin/env bash shebang?
• Do scripts have Google-Style header docs (name, description, author, version, usage, dependencies)?
• Do functions have @param, @return, @example doc comments?
• Is author attribution derived from git config user.name/git config user.email?
• Are scripts idempotent (safe to run multiple times)?

Run: grep -rn "#!/" --include="*.sh" . to find all scripts.

Principle 2 — Bash Script UX with pfb

For each .sh file:

• Is pfb used for terminal output (not plain echo for status messages)?
• Are emojis passed as a parameter, not embedded in the message string?
• Are log levels

Improve

Project: !basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $PWD

Open issues: !gh issue list --state open --json number --jq 'length' 2>/dev/null || echo "unknown"

Last tag: !git describe --tags --abbrev=0 2>/dev/null || echo "none"

Recent commits: !git log --oneline -5 2>/dev/null || echo "none"

Analyses the current project from multiple angles — technical, strategic, and commercial —

then files actionable GitHub issues for every finding.

Step 0: Pre-flight check

gh auth status 2>&1 || { echo "ERROR: gh is not authenticated. Run: gh auth login"; exit 1; }

Step 1: Understand the project

Read these files to build context before analysing anything:

• README.md — stated purpose, audience, and feature set
• CLAUDE.md — current status, decisions, next steps
• Any .claude-plugin/plugin.json or manifest files — metadata and versioning

Then inventory all files:

find . -not -path './.git/*' -type f | sort

Read a representative sample of source files to understand the implementation.

Note: what does this project do, who is it for, and what problem does it solve?

Step 2: Code quality and bugs

Review source files for:

• Logic errors, edge cases, or fragile assumptions
• Anti-patterns or code that will break under realistic conditions
• Inconsistent behaviour between similar components
• Missing error handling at system boundaries (user input, external APIs)
• Unnecessary complexity or premature abstraction
• Hardcoded values that should be configurable

For shell scripts, also check:

bash -n <script.sh>   # syntax check each script

Label findings: bug for defects, enhancement for quality improvements.

Step 3: Feature completeness

Based on the project's stated purpose in README.md, identify:

• Features described but not yet implemented
• Obvious gaps a user of this tool would expect
• Incomplete workflows (things that almost work end-to-end but don't)
• Integration opportunities with tools this project already touches

Label findings: enhancement.

Step 4: Documentation

• Is the README sufficient for a new user to get started without help?
• Are there undocumented behaviours or options?
• Are examples present and accurate?
• Is CLAUDE.md current with the real project state?
• Are there missing or misleading inline comments in complex code?

Label findings: documentation.

Step 5: Secur

Promote Changes

Runs the full release workflow from current working state to a tagged GitHub release on main.

Current branch: !git branch --show-current 2>/dev/null || echo "unknown"

Git status: !git status --short 2>/dev/null || echo "not a git repo"

Last tag: !git describe --tags --abbrev=0 2>/dev/null || echo "none"

Recent commits since last tag:

!`git log $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD --oneline -10 2>/dev/null || git log --oneline -10`

Next version (calculated from commits above):

!`(last=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0"); IFS='.' read -r ma mi pa <<< "${last#v}"; log=$(git log "${last}..HEAD" --format="%s" 2>/dev/null); if echo "$log" | grep -qE "^[a-z]+(\([^)]+\))?!:"; then echo "v$((ma+1)).0.0"; elif echo "$log" | grep -qE "^feat"; then echo "v${ma}.$((mi+1)).0"; else echo "v${ma}.${mi}.$((pa+1))"; fi)`

Step 0: Pre-flight checks

gh auth status 2>&1 || { echo "ERROR: gh is not authenticated. Run: gh auth login"; exit 1; }

Check for untracked .env files that could be accidentally staged:

git status --short | grep -E '^\?\? .*\.env' && echo "WARNING: untracked .env files detected — review before staging"
cat .gitignore 2>/dev/null | grep -q '\.env' || echo "WARNING: .gitignore does not exclude .env files"

If any .env files would be staged:

if [ -t 0 ]; then
  # Interactive — ask for confirmation before continuing
  read -p "WARNING: .env files detected. Continue? (y/N) " confirm
  [[ "$confirm" =~ ^[Yy]$ ]] || { echo "Aborted."; exit 1; }
else
  # Non-interactive — hard stop; too risky to proceed without human review
  echo "ERROR: untracked .env files detected in non-interactive mode. Aborting."
  exit 1
fi

Step 1: Commit any uncommitted changes

If the git status above shows uncommitted or untracked changes:

1. Review the diff: git diff and git diff --cached
2. Stage changes selectively — prefer tracked files: git add -u, then review and add any

intentional new files individually. Avoid git add -A unless the user explicitly confirms.

1. Draft a conventional commit message from the changes — lead with a type prefix

(feat:, fix:, docs:, chore:, etc.) and a concise summary

1. Commit using a heredoc so multi-line

Review PR

PR: !gh pr view --json number,title --jq '"#\(.number): \(.title)"' 2>/dev/null || echo "none"

Fetches a pull request diff, evaluates it against the project's coding standards, security posture,

and test coverage, then posts a structured review and either approves or requests changes.

Step 0: Pre-flight check

gh auth status 2>&1 || { echo "ERROR: gh is not authenticated. Run: gh auth login"; exit 1; }

Determine the PR to review. If the user named a number, use it. Otherwise default to the current

branch's open PR:

gh pr view --json number,title 2>/dev/null || echo "No PR for current branch"

If no PR is found, stop and ask the user which PR number to review.

Step 1: Fetch PR context

gh pr view <number> --json number,title,body,headRefName,baseRefName,author,labels,commits,files

gh pr diff <number>

Also read the project files to understand standards and conventions:

• README.md — stated purpose and feature set
• CLAUDE.md — current decisions and context, if present
• ~/.claude/CLAUDE.md — personal development standards already loaded in context

Step 2: Evaluate the diff

Review the diff against the following criteria. Note findings — positive and negative — for each:

Correctness

• Does the change do what the PR description says?
• Are there logic errors, off-by-one errors, or incorrect conditionals?
• Are edge cases handled?

Coding standards (from ~/.claude/CLAUDE.md)

• Scripts use correct shebang and follow the Bash Style Guide
• Terminal output uses pfb (Bash) or Rich (Python) with correct visual hierarchy
• Functions have Google-style documentation headers
• No hardcoded configuration — environment variables with .env.template
• Error messages are actionable (say what went wrong and what to do)

Security

• No secrets, credentials, or tokens in code or comments
• External input validated at system boundaries
• No command injection risks (unquoted variables in shell, unsanitised input in queries)
• File paths handled safely (no unquoted expansions, no eval on external data)

Test coverage

• Are new code paths exercised by tests?
• Do existing tests still pass (check for any test files modified or added)?
• Are failure paths tested, not just happy paths?

Documentation and markdown

• New or changed markdown passes markdownlint conventions (blank lines around blocks, language on

code fences, line length ≤ 120)