mthds-check

name	mthds-check
description	Check and validate MTHDS bundles for issues. Use when user says "validate this", "check my workflow", "check my method", "does this .mthds make sense?", "review this pipeline", "any issues?", "is this correct?". Reports problems without modifying files. Read-only analysis.
min_mthds_version	0.12.1
allowed-tools	["Bash","Read","Grep","Glob"]

Check MTHDS bundles

Validate and review MTHDS bundles based on the MTHDS standard without making changes.

Process

Step 0 — Environment Check (mandatory, do this FIRST)

Run this command to check toolchain status:

# Wrapped in `bash -c` so the bash array syntax below works even when the
# session shell is zsh.
bash -c '
# Pick the cached env-check from the plugin version with the highest semver.
# Matches both `mthds` (prod) and `mthds-dev` (dev) plugin caches. The padded
# segment trick keeps lex order = semver order so 0.10 does not sort below 0.9.
_best_f=""; _best_k=""
for f in "$HOME/.claude/plugins/cache/"*/mthds*/*/bin/mthds-env-check; do
  [ -x "$f" ] || continue
  _v="${f%/bin/*}"; _v="${_v##*/}"
  _k=""; IFS=. read -ra _parts <<<"${_v%%[-+]*}"
  for _p in "${_parts[@]}"; do _p=${_p%%[!0-9]*}; _k="${_k}$(printf %06d "${_p:-0}")"; done
  [[ "$_k" > "$_best_k" ]] && { _best_f="$f"; _best_k="$_k"; }
done
[ -n "$_best_f" ] && exec "$_best_f" "0.12.1"
echo "MTHDS_ENV_CHECK_MISSING"
'

Interpret the output:

• MTHDS_AGENT_MISSING → STOP. Do not proceed. Tell the user:

The mthds-agent CLI is required but not installed. Install it with:

npm install -g mthds

Then re-run this skill.

• MTHDS_AGENT_VERSION_UNKNOWN → STOP. The installed mthds-agent returned an unparseable version. Tell the user:

Could not parse the output of mthds-agent --version. Your installation may be corrupt. Reinstall with:

npm install -g mthds@latest

Then re-run this skill.

• MTHDS_AGENT_OUTDATED <installed> <required> → The installed mthds-agent is too old for this plugin. Do not hard-stop. Instead, tell the user their mthds-agent (v<installed>) is older than the required v<required>, then follow the upgrade flow to offer upgrading mthds-agent via npm install -g mthds@latest. After the upgrade flow completes (whether the user upgraded or declined), proceed to Step 1. The upgrade flow's "Not now" and "Never ask" options let users continue with current versions.

• MTHDS_UPDATE_CHECK_FAILED ... → WARN. The update check command failed. Show the error output to the user. Suggest checking network connectivity and mthds-agent installation. Proceed to Step 1 with current versions.

• UPGRADE_AVAILABLE ... → Read upgrade flow and follow the upgrade prompts before continuing to Step 1.

• JUST_UPGRADED ... → Announce what was upgraded to the user, then continue to Step 1.

• UP_TO_DATE ... → Proceed to Step 1. The line is a terse list of verified installed versions (e.g. UP_TO_DATE mthds-agent=0.10.0 plxt=0.4.0 plugin=0.12.0); if you mention the env-check in your preamble acknowledgement, relay the agent and plugin versions you saw. Two "explicit-quiet" variants share the same prefix and are also clean — proceed to Step 1 without warning, and do not relay the quiet state unless the user is troubleshooting:

  • UP_TO_DATE update-check=disabled — the user has turned update-check off via config.
  • UP_TO_DATE update-check=snoozed — the user has an active snooze on the current version key; an upgrade would otherwise be available, but they explicitly asked for quiet.

• No output → WARN. The env-check produced no output at all, which usually means mthds-agent itself is broken or the wrapper script bailed before printing. Tell the user the environment check could not be confirmed, then proceed cautiously to Step 1.

• MTHDS_ENV_CHECK_MISSING → WARN. The env-check script was not found at either expected path. Tell the user the environment check could not run, but proceed to Step 1.

• Any other output → WARN. The preamble produced unexpected output. Show it to the user verbatim. Proceed to Step 1 cautiously.

Do not write .mthds files manually, do not do any other work. The CLI is required for validation, formatting, and execution — without it the output will be broken.

No backend setup needed: This skill works without configuring inference backends or API keys. You can start building/validating methods right away. Backend configuration is only needed to run methods with live inference — use /mthds-runner-setup when you're ready.

Step 1: Read the .mthds File

Load and parse the method.

Step 2: Run plxt Lint

Catch TOML syntax and schema errors before semantic validation. This skill is read-only and never triggers the PostToolUse hook, so lint must be run explicitly:

mthds-agent plxt lint <file>.mthds

If lint reports errors, include them in the final report and continue — semantic validation in the next step may reveal additional issues.

Step 3: Run CLI Validation

Use -L pointing to the bundle's own directory to avoid namespace collisions. --graph generates a flowchart:

mthds-agent validate bundle <file>.mthds -L <bundle-directory>/ --graph

Step 4: Parse the JSON Output

• If success: true — all pipes validated, report clean status
• If error — see Error Handling Reference for error types and recovery

Step 5: Cross-Domain Validation

When the bundle references pipes from other domains, use --library-dir (see Error Handling — Cross-Domain).

Step 6: Analyze for Additional Issues

Manual review beyond CLI validation:

• Unused concepts (defined but never referenced)
• Unreachable pipes (not in main_pipe execution path)
• Missing descriptions on pipes or concepts
• Inconsistent naming conventions
• Potential prompt issues (missing variables, unclear instructions)

Step 7: Report Findings

Report by severity:

• Errors: Validation failures from CLI (with error_type and pipe_code) and plxt lint errors
• Warnings: Issues that may cause problems (e.g., model availability)
• Suggestions: Improvements for maintainability
• Flowchart: If validation succeeded, mention the generated dry_run.html flowchart next to the bundle

Step 8: Do NOT Make Changes

This skill is read-only.

What Gets Checked

• TOML syntax and schema validation (via mthds-agent plxt lint)
• Concept definitions and references
• Pipe type configurations
• Input/output type matching
• Variable references in prompts
• Cross-domain references
• Naming convention compliance
• Model reference resolution (dry run)

Reference

• Error Handling — read when CLI returns an error to determine recovery
• MTHDS Agent Guide — read for CLI command syntax or output format details
• MTHDS Language Reference — read when reviewing .mthds TOML syntax
• Native Content Types — read when checking $var.field references in prompts to verify the attribute exists on the content type