NLPM audit findings: 11 bugs and 3 security fixes (NL score 88/100)

[xiaolai]

Automated audit: This issue was generated by NLPM, a natural language programming linter, running via claude-code-action. The findings below are based on static analysis of the plugin artifacts — please evaluate them on their merits and discard anything that doesn't apply to your context.

Overview

NLPM (Natural Language Programming Manager) ran a static audit of this repo. First: this is a well-structured collection with impressive depth — the perf, ship, and audit-project suite in particular are notably rigorous. The overall NL score is 88/100, which is strong for a heterogeneous multi-author collection.

This issue summarizes the findings. PRs have been opened for the mechanical, high-confidence bugs (no judgment calls, just missing required fields). Quality suggestions are listed here as informational only — no PRs for those.

NLPM Methodology

NLPM scores Claude Code NL artifacts (commands, agents, skills, hooks, plugins) on a 100-point scale starting at 100 with deterministic penalty deductions. It checks:

• Required frontmatter fields (description, allowed-tools for commands, tools for agents)
• Cross-component reference integrity
• Security patterns in executable surfaces (hooks, scripts)

Bugs Found (11 total)

Missing YAML frontmatter (5 files)

These files are in commands/ directories but have no frontmatter, so Claude Code cannot register or describe them:

File	Parent command
ship/commands/ship-deployment.md	/ship
ship/commands/ship-ci-review-loop.md	/ship
ship/commands/ship-error-handling.md	/ship
audit-project/commands/audit-project-agents.md	/audit-project
audit-project/commands/audit-project-github.md	/audit-project

Missing tools field in agent (1 file)

File	Issue
test-writer-fixer/agents/test-writer-fixer.md	Has name, description, color but no tools field — tool budget is undefined

Missing allowed-tools in commands (5 files)

These commands describe operations that require specific tools, but declare no allowed-tools — all tool calls are denied:

File	Needs
pr-review/commands/pr-review.md	Bash(git:*), Bash(gh:*), Read, Glob, Grep
commit/commands/commit.md	Bash(git:*), package manager bash
create-pr/commands/create-pr.md	Bash(git:*), Bash(gh:*), Bash(biome:*), Read, Glob
documentation-generator/commands/documentation-generator.md	Read, Write, Edit, Glob, Grep
bug-fix/commands/bug-fix.md	Bash(git:*), Bash(gh:*), Read, Write, Edit, Glob, Grep

Security Findings (Medium severity — safe to fix)

#	File	Issue
1	security-guidance/hooks/security_reminder_hook.py	Debug log writes to world-writable /tmp/security-warnings-log.txt — any local user can read it
2	connect-apps/commands/setup.md	API key interpolated into Python one-liner string literal — fails if key contains a single-quote
3	ship/commands/ship.md	--strategy value used directly as --$STRATEGY flag without allowlist validation

PRs Opened

PR	Files	Status
#182	Add frontmatter to ship reference docs (3 files)	Open
#183	Add frontmatter to audit-project reference docs (2 files)	Open
#184	Add tools field to test-writer-fixer agent	Open
#185	Add allowed-tools to 5 commands	Open
#186	Move security hook debug log from /tmp to ~/.claude/ and gate behind env var	Open

Security findings #2 and #3 were not PRed — they involve logic changes to existing workflows that the original authors are better positioned to review and implement.

Quality Issues (informational, no PRs)

The 34 quality issues are logged in the NLPM audit report and involve things like missing example blocks in perf agents, vague terms in skill descriptions, and missing output format sections. These are real improvements but involve content judgment rather than mechanical fixes — I'll leave those to the maintainers.

Thanks for maintaining this collection — it's a genuinely useful resource for the Claude Code ecosystem.