NLPM audit findings: 4 agent bugs + 2 security fixes (NL score: 77/100)

Automated audit: This issue was generated by NLPM, a natural language programming linter, running via claude-code-action. Please evaluate the findings on their merits.

Hello! This is an automated audit of the NL artifacts (agents, commands, skills) in claude-howto. The project scored 77/100 on the NLPM 100-point quality scale — well above the default 70-point threshold. The plugin structure is clear and the locale consistency (en/vi/zh/uk) is excellent.

What is NLPM?

NLPM is a natural language programming linter for Claude Code plugins. It applies a deterministic 100-point scoring rubric to agent, command, and skill definition files, checking for things like:

• Valid frontmatter fields (model, tools, allowed-tools)
• Examples and output format documentation
• Vague or ambiguous language
• Cross-component reference integrity

Bugs Found (PR-worthy)

These are functional correctness issues, not style preferences:

#	File	Issue	Priority
1	07-plugins/pr-review/agents/security-reviewer.md	tools: diff — diff is not a valid Claude Code tool; agent silently loses diff capability	High
2	vi/07-plugins/pr-review/agents/security-reviewer.md	Same as #1	High
3	zh/07-plugins/pr-review/agents/security-reviewer.md	Same as #1	High
4	uk/07-plugins/pr-review/agents/security-reviewer.md	Same as #1	High

Security Fixes Submitted (Medium/Low only)

#	File	Issue	PR
1	scripts/requirements.txt	All 6 packages fully unpinned (supply-chain risk)	#90
2	scripts/check_cross_references.py	resolve() without repo-root boundary check	#91

PRs Created

• #89 — fix: replace invalid diff tool with bash in security-reviewer agents (Bugs #1–4)
• #90 — fix: pin requirements.txt to known-good versions
• #91 — fix: constrain cross-reference resolution to repo root

Quality Notes (informational, no PRs)

The audit also found 275 quality issues across agents and commands — mainly missing model fields, empty-input handling, and output format documentation. These look intentional for a tutorial/example repo (the stubs illustrate plugin structure). A bulk PR adding model declarations and allowed-tools fields would raise the score from 77 to approximately 88, if that's of interest.

Security Findings (not PR-worthy, for maintainer awareness)

The audit found 3 Medium findings in the Python scripts (subprocess with user-controlled binary path, network calls with markdown-sourced URLs, environment-influenced subprocess args). These all have nosec annotations already and carry low practical risk in a local dev tool context. No Critical or High findings were detected.

---

Thank you for maintaining this well-structured guide to Claude Code! The locale-consistent layout is a great pattern. Happy to clarify any of the findings or close this issue if the PRs are not a good fit for the project.