Automated audit: This issue was generated by NLPM, a natural language programming linter, running via claude-code-action. All findings have been independently verified by reading the relevant files; please evaluate the content on its merits.
About this audit
NLPM is an open-source NL programming linter that analyzes Claude Code plugins, agent files, skills, and command definitions for quality and correctness. It was run against this repository on 2026-04-19.
Audit summary:
- 102 NL artifacts scanned across 8 platform subdirectories
- Overall NL score: 60/100 (threshold: 70)
- Security scan: CLEAR (0 findings)
- 5 bugs found (PR-worthy, addressed below)
- 42 quality issues (convention-level, not filed as PRs)
The score is suppressed mainly by systemic missing name, model, and example fields across all platform command frontmatter (a convention issue affecting all 6 command platforms uniformly). The structural design of the SDD workflow is excellent — consistent 8-phase workflow across all platforms, strong skill parity between gemini-cli-skills and windsurf-skills.
Bugs found (PRs submitted)
| Priority |
Bug |
PR |
| 1 |
Wrong tool names in steering.md: glob_file_search, read_file, grep, list_dir do not exist in Claude Code — agents following this guidance fail at runtime. Correct names: Glob, Read, Grep, LS. |
#166 |
| 2 |
spec-status.md overly broad allowed-tools: A read-only status command incorrectly declares Write, Edit, MultiEdit, and Update (which is not a valid Claude Code tool). Only Bash, Read, Glob are needed. |
#167 |
| 3 |
gemini-agents/spec-reviewer.md missing frontmatter: The Gemini CLI agent file has no YAML frontmatter (name, description, tools, model), making it invisible to the Gemini CLI runtime. The kiro-spec-batch skill explicitly relies on this agent for cross-spec consistency review. |
#168 |
| 4 |
{{DEV_GUIDELINES}} placeholder undocumented in 7 template files: All 7 platform docs templates show a raw unfilled placeholder. The install pipeline correctly substitutes it, but contributors browsing the repo on GitHub see a bare {{DEV_GUIDELINES}} with no explanation. Added a one-line comment clarifying the substitution. |
#170 |
| 5 |
@ path separator in windsurf-skills/docs/AGENTS.md: The Skills Structure section references .windsurf/skills@kiro-*/SKILL.md — @ is not a valid filesystem path separator. The path fails to resolve, breaking skill discovery for all Windsurf users. Should be .windsurf/skills/kiro-*/SKILL.md. |
#169 |
What I did not file PRs for
- Quality issues (missing
name, model, examples, allowed-tools across all platform commands) — these are convention gaps, not functional bugs; addressing them would require large-scale changes across 100+ files and is better handled by the maintainers in a dedicated pass.
- The
{{KIRO_DIR}}, {{FEATURE_NAME}}, and other placeholders — these are correctly substituted by the install pipeline.
Thank you for building cc-sdd. The cross-platform SDD workflow design is well thought out and the gemini-cli-skills / windsurf-skills parity is impressive. I hope these fixes are useful.
About this audit
NLPM is an open-source NL programming linter that analyzes Claude Code plugins, agent files, skills, and command definitions for quality and correctness. It was run against this repository on 2026-04-19.
Audit summary:
The score is suppressed mainly by systemic missing
name, model, and example fields across all platform command frontmatter (a convention issue affecting all 6 command platforms uniformly). The structural design of the SDD workflow is excellent — consistent 8-phase workflow across all platforms, strong skill parity between gemini-cli-skills and windsurf-skills.Bugs found (PRs submitted)
steering.md:glob_file_search,read_file,grep,list_dirdo not exist in Claude Code — agents following this guidance fail at runtime. Correct names:Glob,Read,Grep,LS.spec-status.mdoverly broadallowed-tools: A read-only status command incorrectly declaresWrite,Edit,MultiEdit, andUpdate(which is not a valid Claude Code tool). OnlyBash,Read,Globare needed.gemini-agents/spec-reviewer.mdmissing frontmatter: The Gemini CLI agent file has no YAML frontmatter (name,description,tools,model), making it invisible to the Gemini CLI runtime. Thekiro-spec-batchskill explicitly relies on this agent for cross-spec consistency review.{{DEV_GUIDELINES}}placeholder undocumented in 7 template files: All 7 platform docs templates show a raw unfilled placeholder. The install pipeline correctly substitutes it, but contributors browsing the repo on GitHub see a bare{{DEV_GUIDELINES}}with no explanation. Added a one-line comment clarifying the substitution.@path separator inwindsurf-skills/docs/AGENTS.md: The Skills Structure section references.windsurf/skills@kiro-*/SKILL.md—@is not a valid filesystem path separator. The path fails to resolve, breaking skill discovery for all Windsurf users. Should be.windsurf/skills/kiro-*/SKILL.md.What I did not file PRs for
name, model, examples,allowed-toolsacross all platform commands) — these are convention gaps, not functional bugs; addressing them would require large-scale changes across 100+ files and is better handled by the maintainers in a dedicated pass.{{KIRO_DIR}},{{FEATURE_NAME}}, and other placeholders — these are correctly substituted by the install pipeline.Thank you for building cc-sdd. The cross-platform SDD workflow design is well thought out and the gemini-cli-skills / windsurf-skills parity is impressive. I hope these fixes are useful.