mthds-run

name	mthds-run
description	Run MTHDS methods and interpret results. Use when user says "run this pipeline", "execute the workflow", "execute the method", "test this .mthds file", "try it out", "see the output", "dry run", or wants to execute any MTHDS method bundle and see its output.
min_mthds_version	0.12.1

Run MTHDS methods

Execute MTHDS method bundles and interpret their JSON output.

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 (Codex runs blocks under the user's shell).
bash -c '
# Pick the cached env-check from the plugin version with the highest semver.
# Pad each numeric segment to fixed width so lex sort matches semver sort
# (avoids the 0.10 < 0.9 lex-order trap). Sort keys are digits-only by
# construction, so the [[ > ]] compare is locale-independent. Bash 3.2 OK.
_best_f=""; _best_k=""
for f in "${CODEX_HOME:-$HOME/.codex}"/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" --codex
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.

• CODEX_CONFIG_NEEDS_SETUP → Codex's ~/.codex/ is not set up for the mthds plugin, so the bundled .mthds validation hook will not load. When this fires it is the only terminal status the env-check emits — update-check is skipped entirely (not run, not suppressed) because fixing the hook is the prerequisite and update-check's upgrade marker is one-shot; the user re-runs and gets fresh update info next time. The env-check may print one or more #-prefixed diagnostic lines after the status — relay them if present. Resolve this before Step 1:

  1. Preview — run mthds-agent codex apply-config --dry-run and show the user the output. WOULD_APPLY lists the keys it will add under applied; ALREADY_OK means no keys need adding. Either way, relay any warnings entries — those (e.g. read-only sandbox, hooks disabled) need a hand-fix apply-config will not perform. If ALREADY_OK with no warnings, treat as resolved and go to Step 1.
  2. Ask — use AskUserQuestion: "Apply Codex config now?" with options "Apply now" / "Skip".
  3. Apply now — run mthds-agent codex apply-config:
     • APPLIED / ALREADY_OK → tell the user the config is fixed and they must restart Codex for the validation hook to load (it will not load in this session). Relay any warnings — those still need a hand-fix.
     • Error about conflicting keys → show it verbatim; the user must hand-edit ~/.codex/config.toml, then re-run mthds-agent codex apply-config.
     • Error from the sandbox blocking the write to ~/.codex/config.toml → ask the user to run mthds-agent codex apply-config themselves in a terminal, then restart Codex.
  4. Skip — tell the user the validation hook stays off until they run mthds-agent codex apply-config and restart Codex.

  Then proceed to Step 1. This session has no PostToolUse hook. The mthds skills still run mthds-agent validate bundle explicitly, so .mthds files built or edited through a skill are still semantically validated — but the write-time plxt lint/fmt pass depends on the hook and will not run until Codex is restarted.

• 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.

Step 1 — Pipelex Runtime Check (mandatory)

Running methods requires the Pipelex runtime to be installed and configured. The preamble (Step 0) already verifies mthds-agent and its managed binaries are present and up to date. This step checks Pipelex-specific configuration health.

mthds-agent doctor  # outputs markdown

• If the doctor reports config issues (missing backends, missing API keys) AND the user is requesting a live run (not --dry-run): STOP. Tell the user:

Pipelex needs to be configured with inference backends before running methods. Use /mthds-runner-setup for guided configuration.

• If the user is requesting a dry run (--dry-run): config issues are OK — dry runs work without backend configuration. Proceed.

• If healthy: proceed to Step 2.

Step 2: Identify the Target

Target	Command
Pipeline directory (recommended)	mthds-agent run bundle <bundle-dir>/
Specific pipe in a directory	mthds-agent run bundle <bundle-dir>/ --pipe my_pipe
Bundle file directly	mthds-agent run bundle bundle.mthds -L <bundle-dir>/
Pipe by code from library	mthds-agent run bundle my_pipe

Directory mode (recommended): Pass the pipeline directory as target. The CLI auto-detects bundle.mthds, inputs.json, and sets -L automatically — no need to specify them explicitly. This also avoids namespace collisions with other bundles.

Step 3: Prepare Inputs and Check Readiness

Fast path — inputs just prepared

If inputs were already prepared during this conversation — via /mthds-inputs (user-data, synthetic, or mixed strategy), or by manually assembling inputs.json with real values earlier in this session — skip the schema fetch and readiness check. The inputs are ready. Proceed directly to Step 4 with a normal run.

This applies when you just wrote or saw inputs.json being written with real content values. It does NOT apply after /mthds-build (which saves a placeholder template) or after /mthds-inputs with the template strategy.

Full check — cold start

If /mthds-run is invoked without prior input preparation in this session, perform the full readiness check:

Get the input schema for the target:

mthds-agent inputs bundle bundle.mthds

Output:

{
  "success": true,
  "pipe_code": "process_document",
  "inputs": {
    "document": {
      "concept": "native.Document",
      "content": {"url": "url_value"}
    },
    "context": {
      "concept": "native.Text",
      "content": {"text": "text_value"}
    }
  }
}

Fill in the content fields with actual values. For complex inputs, use the /mthds-inputs skill.

Input Readiness Check

Before running, assess whether inputs are ready. This prevents runtime failures from placeholder values.

No inputs required: If mthds-agent inputs bundle <file>.mthds returns an empty inputs object ({}), inputs are ready — skip to Step 4.

Inputs required: If inputs exist, check inputs.json for readiness:

1. Does inputs.json exist in the bundle directory?
2. If it exists, scan all content values for placeholder signals:
   • Template defaults: "url_value", "text_value", "number_value", "integer_value", "boolean_value", or any value matching the pattern *_value
   • Angle-bracket placeholders: values containing <...> (e.g. <path-to-cv.pdf>, <your-text-here>)
   • Non-existent file paths: url fields pointing to local files that don't exist on disk

Readiness result:

• Ready: inputs.json exists AND all content values are real (no placeholders, referenced files exist) → proceed to Step 4 with normal run
• Not ready: inputs.json is missing, OR contains any placeholder values → proceed to Step 4 with dry-run fallback

Step 4: Choose Run Mode

If inputs are not ready

Default to --dry-run --mock-inputs and inform the user:

"The inputs for this pipeline contain placeholder values (not real data). I'll do a dry run with mock inputs to validate the pipeline structure."

After the dry run, use AskUserQuestion to present next steps:

• Question: "What would you like to do next?"
• Header: "Next step"
• Options:
  1. Prepare real inputs — "Use /mthds-inputs to fill in actual values, then re-run."
  2. Provide files — "Supply file paths for document/image inputs."
  3. Keep dry run — "Accept the dry-run result as-is."

Run modes reference

Mode	Command	Use When
Dry run + mock inputs	mthds-agent run bundle <bundle-dir>/ --dry-run --mock-inputs	Quick structural validation, no real data needed, or inputs not ready
Dry run with real inputs	mthds-agent run bundle <bundle-dir>/ --dry-run	Validate input shapes without making API calls (auto-detects inputs.json)
Full run	mthds-agent run bundle <bundle-dir>/	Production execution (auto-detects inputs.json)
Full run inline	mthds-agent run bundle <bundle-dir>/ --inputs '{"theme": ...}'	Quick execution with inline JSON inputs
Full run without graph	mthds-agent run bundle <bundle-dir>/ --no-graph	Execute without generating graph visualization
Full run with memory	mthds-agent run bundle <bundle-dir>/ --with-memory	When piping output to another method

Graph by default: Execution graphs (live_run.html / dry_run.html) are now generated automatically. Use --no-graph to disable.

Inline JSON for Inputs

The --inputs flag accepts both file paths and inline JSON. The CLI auto-detects: if the value starts with {, it is parsed as JSON directly. This is the fastest path — no file creation needed for simple inputs.

# Inline JSON
mthds-agent run bundle <bundle-dir>/ --inputs '{"theme": {"concept": "native.Text", "content": {"text": "nature"}}}'

# File path (auto-detected in directory mode)
mthds-agent run bundle <bundle-dir>/

Step 5: Present Results

After a successful run, always show the actual output to the user — never just summarize what fields exist.

Output format modes

The CLI has two output modes:

• Compact (default): stdout is the concept's structured JSON directly — no envelope, no success wrapper. This is the primary output of the method's main concept. Parse the JSON directly for field access.
• With memory (--with-memory): stdout has main_stuff (with json, markdown, html renderings) + working_memory (all named stuffs and aliases). Use this when piping output to another method.

The output_file and graph_files are written to disk as side effects (paths appear in logs/stderr), not in compact stdout.

5a. Determine what to show

In compact mode (default), the output is the concept JSON directly. Show the fields to the user:

{
  "clauses": [...],
  "overall_risk": "high"
}

In --with-memory mode, the output structure depends on the pipe architecture:

main_stuff is always the primary output for a completed run:
    → a value, or an explicit absence document for optional outputs

Pipe Type	main_stuff present?	What to show
PipeLLM, PipeCompose, PipeExtract, PipeImgGen, PipeSearch	Always	main_stuff
PipeSequence	Always (last step)	main_stuff
PipeBatch	Always (list)	main_stuff
PipeCondition	Always	main_stuff
PipeParallel	Always (combined result)	main_stuff

5b. Show the output content

In compact mode: show the JSON fields directly. For structured concepts, format for readability.

In --with-memory mode:

• Show main_stuff.markdown directly — this is the human-readable rendering. Display it as-is so the user sees the full output.
• For structured concepts with fields, also show main_stuff.json formatted for readability.
• If main_stuff is an absence document (absent: true), show the absence reason and provenance instead of treating it as missing output.

For dry runs: Show the same output but clearly label it as mock/simulated data.

5c. Output file

• The CLI automatically saves the full JSON output next to the bundle (live_run.json or dry_run.json).
• The output file path appears in runtime logs (stderr), not in compact stdout.

5d. Present graph files

• Graph visualizations are generated by default (live_run.html / dry_run.html). Use --no-graph to disable.
• Live runs also write live_run_graph.json (the graph spec) next to the bundle.
• The graph file paths appear in runtime logs (stderr), not in compact stdout.

5e. Mention intermediate results

• If the pipeline has multiple steps, briefly note key intermediate values from working_memory (e.g., "The match analysis intermediate step scored 82/100").
• Offer: "I can show the full working memory if you want to inspect any intermediate step."

5f. Suggest next steps

• Re-run with different inputs
• Adjust prompts or pipe configurations if output quality needs improvement

Step 6: Handle Errors

If the run returns InferenceSetupRequiredError (error_domain: onboarding): This means inference has never been configured. This is the user's first live inference run — congratulate them on reaching this milestone, then immediately begin the /mthds-runner-setup flow inline (do not ask the user to type it separately). Follow the full process from that skill to guide them through Gateway or BYOK setup, then re-run the method.

For all other error types and recovery strategies, see Error Handling Reference.

Execution Graphs

Execution graph visualizations are generated by default alongside the run output. Use --no-graph to disable.

mthds-agent run bundle <bundle-dir>/

Graph files (live_run.html / dry_run.html) are written to disk next to the bundle. Live runs additionally produce live_run_graph.json (the graph spec). Their paths appear in runtime logs on stderr, not in compact stdout. When using --with-memory, graph_files is included in the returned JSON envelope.

Piping Methods

The run command accepts piped JSON on stdin when --inputs is not provided. This enables chaining methods:

mthds-agent run method extract-terms --inputs data.json --with-memory \
  | mthds-agent run method assess-risk --with-memory \
  | mthds-agent run method generate-report

When methods are installed as CLI shims, the same chain is:

extract-terms --inputs data.json --with-memory \
  | assess-risk --with-memory \
  | generate-report

• Use --with-memory on intermediate steps to pass the full working memory envelope.
• The final step omits --with-memory to produce compact output.
• --inputs always overrides stdin when both are present.
• Upstream stuff names are matched against downstream input names. Method authors should name their outputs to match the downstream's expected input names.

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 for .mthds syntax documentation
• Native Content Types — read when interpreting pipeline outputs or preparing input JSON, to understand the attributes of each content type