validate-plugin-consistency

Validate Plugin Consistency

After modifying the sdlc-utilities plugin, run this validation to catch structural issues that would cause failures in users' repositories.

When to Use

Invoke this skill when you have modified any of:

• plugins/sdlc-utilities/skills/*/SKILL.md
• plugins/sdlc-utilities/scripts/*.js

Step 1 — Run the Validation Script

node .claude/skills/validate-plugin-consistency/check-consistency.js

If the script exits 0: all checks pass — proceed.

If the script exits 1: fix each issue before finishing the task (see Step 2).

If the script exits 2: run from the repository root or pass --project-root <path>.

Step 2 — Fix Issues Found

For each finding, apply the appropriate fix:

script-resolution-order (error)

The find pattern searches CWD (.) before ~/.claude/plugins. Reverse the order:

# Correct (plugins-first)
SCRIPT=$(find ~/.claude/plugins -name "<script>.js" 2>/dev/null | sort -V | tail -1)
[ -z "$SCRIPT" ] && [ -f "plugins/sdlc-utilities/scripts/<script>.js" ] && SCRIPT="plugins/sdlc-utilities/scripts/<script>.js"
[ -z "$SCRIPT" ] && { echo "ERROR: Could not locate <script>.js. Is the sdlc plugin installed?" >&2; exit 2; }

script-resolution-version (error)

The find ~/.claude/plugins ... | head -1 pipeline picks an arbitrary cached version when multiple plugin versions are present in ~/.claude/plugins/cache/sdlc-marketplace/sdlc/ (filesystem-traversal order, not version order). Replace | head -1 with | sort -V | tail -1 to deterministically select the newest semver. See #258.

# Correct
SCRIPT=$(find ~/.claude/plugins -name "<script>.js" -path "*/sdlc*/scripts/<script>.js" 2>/dev/null | sort -V | tail -1)

skill-runs-script (error)

A skill is paired with a prepare script but does not contain the find+node resolution pattern. Skills must run their own prepare scripts. Add the find+mktemp+node block to the skill following the pattern in review-sdlc/SKILL.md:

1. Skill: find script → $(node "$SCRIPT" --output-file $ARGUMENTS --json) → read and parse JSON

skill-uses-output-file (error)

A skill runs a prepare script but pipes output directly instead of using --output-file capture. Replace with:

MANIFEST_FILE=$(node "$SCRIPT" --output-file $ARGUMENTS --json)
EXIT_CODE=$?

skill-checks-exit-code (error)

A skill runs a script but doesn't capture EXIT_CODE. Add after the node call:

EXIT_CODE=$?
# Exit code 1: show the stderr message to the user and stop.
# Exit code 2: show "Script error — see output above" and stop.

skill-passes-arguments (warning)

A skill runs a prepare script but doesn't use $ARGUMENTS. Change the node invocation to: node "$SCRIPT" $ARGUMENTS --json > "$MANIFEST_FILE"

frontmatter-field-names (error)

A skill uses the deprecated user-invokable field. Replace with user-invocable.

user-invocable-flag (error)

A user-facing skill is missing user-invocable: true in its frontmatter. Add it:

---
name: <skill-name>
description: "..."
user-invocable: true
---

The 10 user-facing skills that must have this flag are: plan-sdlc, execute-plan-sdlc, pr-sdlc, review-sdlc, received-review-sdlc, commit-sdlc, version-sdlc, jira-sdlc, ship-sdlc, setup-sdlc.

docs-skill-existence (error)

A skill directory exists under plugins/sdlc-utilities/skills/<name>/ but has no matching documentation file at docs/skills/<name>.md. Create the doc file using docs/skill-doc-template.md as the starting point.

skills-meta-existence (error)

A user-invocable skill has no matching slug entry in site/src/data/skills-meta.ts. Add an entry to the skillsMeta array with the correct slug, command, category, tagline, pipeline, and connections. See existing entries for the format.

readme-skills-table (warning)

A user-invocable skill is not listed in the README.md skills table. Add a row following the format: | [\/<name>`](docs/skills/<name>.md) | description |`

temp-file-cleanup (warning)

A skill uses mktemp to create a temp file but has no cleanup reference (rm -f, rm -rf, or "clean" in narrative). Add cleanup instructions to the skill, ensuring temp files are removed on all exit paths (success, error, cancellation).

Step 3 — Re-run Validation

After fixing all issues:

node .claude/skills/validate-plugin-consistency/check-consistency.js

Confirm exit 0 before marking work complete.

Reference: The Correct Skill Pattern (for paired skills)

Every skill that has a matching *-prepare.js script must follow this exact pattern:

# Step 0: Resolve and run the prepare script
SCRIPT=$(find ~/.claude/plugins -name "<name>-prepare.js" 2>/dev/null | sort -V | tail -1)
[ -z "$SCRIPT" ] && [ -f "plugins/sdlc-utilities/scripts/<name>-prepare.js" ] && SCRIPT="plugins/sdlc-utilities/scripts/<name>-prepare.js"
[ -z "$SCRIPT" ] && { echo "ERROR: Could not locate <name>-prepare.js. Is the sdlc plugin installed?" >&2; exit 2; }

CONTEXT_FILE=$(node "$SCRIPT" --output-file $ARGUMENTS --json)
EXIT_CODE=$?
# Cleanup: rm -f "$CONTEXT_FILE" after use

# On non-zero EXIT_CODE:
# Exit code 1: show stderr message to the user and stop.
# Exit code 2: show "Script error — see output above" and stop.

# Step 1: Read and parse CONTEXT_FILE as CONTEXT_JSON, then proceed with skill logic.