/swmm-end-to-end

name: swmm-end-to-end
description: Top-level orchestration skill for agentic SWMM modelling. Use when an agent needs one entrypoint that decides which module tools to run, in what order, and when to stop, for example to build, run, QA, and optionally calibrate a SWMM case from prepared or partially prepared inputs.

SWMM End-to-End Orchestration

Part of [Agentic SWMM](https://github.com/Zhonghao1995/agentic-swmm-workflow) — install the project first for the executable toolchain (aiswmm CLI, SWMM solver, MCP servers).

What this skill provides

• A top-level orchestration contract for the agent runtime.
• A stable handoff point for Agentic AI project memory in `memory/initial/`.
• A deterministic execution order across the existing module skills:
• `swmm-canada` (entry skill for Canadian AOIs — real municipal pipes where covered, synthesized elsewhere in Canada)
• `swmm-anywhere` (entry skill for data-scarce regions outside Canada — no real pipe data)
• `swmm-gis`
• `swmm-climate`
• `swmm-params`
• `swmm-network`
• `swmm-builder`
• `swmm-runner`
• `swmm-design-review`
• `swmm-plot`
• `swmm-calibration`
• `swmm-uncertainty`
• `swmm-lid-optimization`
• `swmm-experiment-audit`

Routing rule — real-data path vs synth-data path

The orchestrator MUST inspect the user's inputs before choosing the entry skill:

• If the request includes any of `.shp`, `.csv`, `network.json`, a CAD file, or an existing `.inp` path → the user has real data; route to `swmm-network` (or `swmm-builder` if the INP is already prepared).
• If the request includes only a **bbox** or a **location name** with no pipe-network file attached → check the country first. For a **Canadian** AOI route to `swmm-canada` (the SWMMCanada upstream returns real published municipal storm pipes where a supported city covers the AOI, synthesized elsewhere in Canada). Outside Canada route to `swmm-anywhere`, which produces a synth `.inp`. Either way, downstream skills (`swmm-runner`, `swmm-experiment-audit`, `swmm-plot`) consume the result identically to a real-data INP.
• If both signals appear (bbox **and** a SHP) → prefer the real-data path (`swmm-network`); only fall back to `swmm-anywhere` if the user explicitly asks for a synth baseline for comparison.
• Clear stop conditions so the agent does not pretend a full model was built when critical inputs are still missing.
• A minimal real-data fallback path for Tod Creek via `scripts/real_cases/run_todcreek_minimal.py`.
• A mandatory audit handoff that consolidates artifacts, metrics, QA, comparison records, and default Obsidian audit notes after success or failure.

When to use this skill

Use this skill when the user asks for:

• one agent-facing entrypoint for SWMM modelling,
• end-to-end build + run + QA,
• an agent to decide which SWMM module comes next,
• a real-data dry run before full automation is ready, or
• a bounded orchestration layer without rewriting the underlying scripts.

Do **not** use this skill when the user clearly wants only one module in isolation, such as only rainfall formatting or only calibration metrics.

Recommended public memory preload

Before using this skill in Codex, OpenClaw, Hermes, or another compatible runtime, load the Markdown files in `memory/initial/`:

1. `identification_memory.md` 2. `soul.md` 3. `operational_memory.md` 4. `modeling_workflow_memory.md` 5. `evidence_memory.md` 6. `user_bridge_memory.md`

Those files define the public project identity, agent posture, evidence boundaries, and first-run user behavior. This skill remains the execution contract; the memory files should shape decisions and communication, not replace tool calls or depend on the maintainer's private local workspace.

Supported operating modes

Mode 0: MCP-first framework smoke test mode

Use this when the user is testing the Agentic SWMM framework itself, especially with prompts like "test the end-to-end framework", "test skill and MCP tool calls", "from raw data to INP", or "automatic modeling smoke test".

This mode tests orchestration behavior before scientific model quality. It must:

• trigger this `swmm-end-to-end` skill first;
• choose the smallest real-data subset that can exercise the chain;
• call the relevant MCP tool contracts as the primary path;
• Do not bypass MCP tool contracts by calling the underlying Python scripts as the primary path;
• use temporary script edits only for missing framework adapters that do not yet have MCP coverage;
• record every temporary script fallback as missing framework capability, not as a completed MCP feature.

The run manifest for this mode must include:

• `tool_transport`: `mcp` when the MCP server was called through the protocol, `script_fallback` when the tool contract exists but the MCP transport was bypassed, or `temporary_script` when no MCP contract exists yet;
• `mcp_tool_calls`: ordered records of the intended or actual tool calls, including server, tool name, input paths, output paths, and status;
• `missing_or_fallback_inputs`: explicit data gaps and assumptions such as missing soil, nonnumeric pipe diameter fallback, inferred outfall, inferred invert elevation, or shortened rainfall window;
• `framework_gaps`: MCP/skill gaps discovered during the run that should be implemented later.

Use `scripts/mcp_stdio_call.py` when Codex needs to verify the MCP transport directly from this repository. The helper initializes a server over stdio, checks `tools/list`, calls one tool with JSON arguments, and stores the raw MCP response as an artifact. Use repo-root relative paths in the JSON arguments; the helper resolves those to absolute paths before sending the tool call so server-local working directories do not corrupt path resolution.

For a raw-data to INP smoke test, prefer this MCP call order when inputs are present: 1. `swmm-gis-mcp.qgis_area_weighted_params` for land-use/soil area-weighted params, or record a missing-input fallback if soil is absent. 2. `swmm-climat