ras-commander

Create deterministic paired RASMapper and RAS Commander MapLibre evidence bundles from one review specification. Use when comparing a HEC-RAS model in RASMapper with its web viewer, validating map/tree/legend fidelity on desktop and mobile, checking nodata/extent/default layers, or establishing visual regression fixtures with fixed numeric COG probes.

Capture HEC-RAS and standalone RASMapper windows through current ras-commander Win32 APIs for documentation, debugging, QA/QC evidence, galleries, and deterministic spatial review packages. Use for screenshot, visible-window capture, RASMapper snapshot, dialog capture, or model gallery requests on Windows.

Use RASMapper layer and view automation for spatial QA/QC, contextual model review, and documentation screenshots. Launches standalone RasMapper.exe, toggles reference maps, basemaps, terrain, results, and geometry elements, zooms to HDF-derived extents, enables Update Legend with View, and captures snapshots for agent review.

Pause agent work and request explicit human input at hard gates where professional judgment, public API compatibility, HEC-RAS execution, agent infrastructure, or git/release operations create material risk. Triggers: human-in-the-loop, HITL, human approval, human decision, approval gate, hard gate, public API change, engineering assumption, HEC-RAS execution approval, agent infrastructure change, release gate.

Codex-native adapter for invoking Anthropic Claude Code CLI as an independent read-only QAQC reviewer using markdown file handoff. Use when the user explicitly asks Codex to ask Claude, Claude Code, Opus, or Anthropic for a QAQC/code review, second-model review, or independent review. Do not trigger for generic QAQC unless the user asks for Claude specifically. Triggers: claude review, claude code review, ask claude, invoke claude, claude qaqc, opus review, anthropic review, second model with claude Prerequisites: Claude Code CLI authenticated and available as `claude`. Default model: opus with xhigh effort for deep reviews; use sonnet/high for faster or lower-cost review passes.

Enforce the feature branch workflow — intercept any attempt to merge, push, or commit directly to main and redirect to the correct feature branch process. Triggers on "merge to main", "push to main", "PR to main", or any operation targeting the main branch.

Delegate code tasks to OpenAI Codex CLI using markdown file handoff pattern. Write instructions to TASK.md, Codex reads and executes, outputs to OUTPUT.md. Use for implementation, refactoring, code generation requiring extended thinking. Triggers: codex, codex cli, delegate to codex, codex subagent, implementation task, refactoring task, code generation, gpt-5.2-codex, openai codex, extended thinking, multi-file changes, complex implementation Prerequisites: Codex CLI authenticated (codex login or OPENAI_API_KEY) Model: gpt-5.2-codex (default, supports xhigh reasoning effort)

Legacy Claude-only provider orchestration for Google Gemini CLI using markdown file handoff. Write review request to REVIEW.md, Gemini analyzes, outputs findings to FINDINGS.md. Use only when the user explicitly requests Gemini. Do not trigger for generic QAQC, quality assurance, security review, architecture review, or second-opinion requests. Triggers: gemini, gemini cli, delegate to gemini, gemini subagent, gemini-3-pro-preview, gemini-3-flash-preview Prerequisites: Gemini CLI authenticated (gemini login or GEMINI_API_KEY) Models: gemini-3-pro-preview (default), gemini-3-flash-preview (large context)

Legacy Claude-only provider orchestration for Opencode CLI using Kimi K2.5 via markdown file handoff. Write test request to TASK.md, Opencode with Kimi K2.5 generates tests/reviews, outputs to OUTPUT.md. Use only when the user explicitly requests Kimi or Opencode/Kimi. Do not trigger for generic QAQC, testing, security review, edge case, or coverage requests. Triggers: kimi, kimi k2.5, kimi cli, opencode kimi, kimisubagent, togetherai kimi, opencode/kimi-k2.5-free, togetherai/moonshotai/Kimi-K2.5 Prerequisites: Opencode CLI installed, Together.ai API key (if using togetherai provider) Models: opencode/kimi-k2.5-free (recommended), togetherai/moonshotai/Kimi-K2.5 (alternative)

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. Triggers: worktree, git worktree, isolated workspace, feature branch isolation, multiple branches, parallel development, branch workspace, create worktree, manage worktree, close worktree, worktree cleanup, isolated branch, side branch, concurrent development, worktree list, worktree status.

Reads HEC-DSS files (V6 and V7) for boundary condition extraction using RasDss class. Handles JVM configuration, HEC Monolith download, catalog reading, and time series extraction. Use when working with DSS files, extracting boundary data, reading HEC-HMS output, integrating DSS workflows with HEC-RAS, cataloging DSS file contents, or converting DSS data to pandas DataFrames. Triggers: DSS, HEC-DSS, boundary condition, time series, JVM, Java, catalog, pathname, HEC-HMS, Monolith, pyjnius, read DSS, extract DSS, DSS boundary, DSS catalog, DSS DataFrame, DSS V6, DSS V7.

Crawl FEMA's public BLE/eBFE S3 bucket to build a catalog of available Base Level Engineering datasets by state, HUC, and watershed. Cache results locally. Use when discovering what BLE models are available for a region before download.

Organize downloaded FEMA eBFE/BLE model files into standardized 4-folder structure. Use when working with eBFE downloads that need organization into: - HMS Model/ (HEC-HMS hydrologic models) - RAS Model/ (HEC-RAS hydraulic models) - Spatial Data/ (GIS, terrain, geodatabases) - Documentation/ (reports, PDFs, metadata) Handles variable archive structures, nested zips, and mixed content through intelligent file analysis and recursive extraction.

Validate organized eBFE/BLE model using ras-commander dataframes. Uses init_ras_project() then checks plan_df, boundary_df, rasmap_df to verify: - All plan files exist - All DSS files exist with relative paths - All terrain files exist with relative paths - All HDF results accessible - No absolute paths (would cause GUI popups) Use after organizing eBFE model to verify it's actually runnable. Generates validation report and script for user re-verification. Triggers: validate eBFE, validate BLE, verify model, check model, eBFE validation, BLE validation, plan_df check, boundary_df check, rasmap_df check, DSS path validation, terrain path validation, absolute path detection, GUI popup prevention, model verification, organized model check, post-organize validation.

Executes HEC-RAS plans using RasCmdr.compute_plan(), handles parallel execution across multiple plans, manages destination folders, and monitors real-time progress with callbacks. Use when running HEC-RAS simulations, computing plans, executing models, parallel workflows, setting up distributed computation, batch processing, scenario analysis, or monitoring execution progress in real-time. Triggers: execute, run, compute, HEC-RAS, plan, simulation, parallel, callback, batch, scenario, destination folder, worker, monitoring, progress, real-time.

Executes HEC-RAS plans using RasControl class via HECRASController COM interface for legacy HEC-RAS versions (3.x-5.x). Handles COM lifecycle management, session tracking, orphan cleanup, steady/unsteady result extraction, and watchdog protection for Jupyter notebooks. Use when automating legacy HEC-RAS, extracting results from older versions, comparing across HEC-RAS versions, or needing COM-based automation that RasCmdr cannot provide. Triggers: RasControl, HECRASController, COM, legacy, HEC-RAS 4, HEC-RAS 5, win32com, steady results, unsteady results, version comparison, COM interface, legacy automation, 3.x, 4.x, 5.x, orphan cleanup, watchdog, session tracking.

Distributed HEC-RAS execution across remote workers (PsExec, Docker, SSH, cloud). Handles worker initialization, queue scheduling, and result aggregation. Use when setting up remote execution, distributed computation, cloud workflows, scaling HEC-RAS across machines, parallel processing on multiple computers, Windows remote execution, container-based execution, session-based remote execution, PsExec configuration, Docker worker setup, or multi-machine HEC-RAS workflows. Triggers: remote execution, distributed execution, PsExec, Docker worker, SSH execution, cloud execution, parallel remote, multi-machine, session_id, remote worker, worker initialization, queue scheduling, network share, container execution.

Explores the HEC-RAS GUI to document menus, dialogs, controls, and workflows using win32com automation with screenshot capture. Use when needing to discover menu structure, document dialog controls, capture screenshots for documentation, or explore unfamiliar GUI elements in HEC-RAS. Triggers: explore GUI, screenshot, capture dialog, document menu, HEC-RAS interface, discover controls, GUI automation, menu exploration, dialog documentation, visual documentation.

Export HEC-RAS geometry and simulation results to cloud-native formats: GeoParquet, PMTiles (vector and raster), and PostGIS. Uses ras2cng as a CLI wrapper over ras-commander parsers. Use when exporting HEC-RAS mesh geometry to GeoParquet, publishing results as PMTiles for web maps, querying HEC-RAS outputs with DuckDB SQL, syncing flood results to PostGIS, converting HEC-RAS to cloud-native geospatial formats, or generating vector tiles from simulation outputs. Keywords: GeoParquet, PMTiles, DuckDB, PostGIS, cloud-native, vector tiles, geometry export, mesh cells, cross sections, ras2cng.

Extract HEC-RAS hydraulic results from HDF files including water surface elevations (WSE), depths, velocities, and flows for both steady and unsteady simulations. Handles cross section time series, 2D mesh results, maximum envelopes, and dam breach results. Use when you need to extract, analyze, or post-process HEC-RAS simulation outputs, retrieve water levels, query velocity fields, get depth grids, extract flow data, analyze breach hydrographs, or pull hydraulic variables from .hdf result files. Triggers: HDF results, extract WSE, water surface elevation, depth grid, velocity, flow data, mesh results, cross section time series, maximum envelope, breach results, HdfResultsPlan, HdfResultsMesh, HdfResultsBreach, steady results, unsteady results, plan HDF, .p01.hdf, get_wse, get_depth, get_velocity, post-process, simulation output.

Parse HEC-RAS compute output from HDF files to extract execution status, diagnostic messages, and performance metrics. Converts raw computation messages into structured diagnostics for workflow orchestration. Use when checking plan completion status, extracting compute messages, diagnosing execution failures, analyzing runtime performance, or interpreting HEC-RAS error codes. Keywords: compute messages, execution status, plan complete, runtime, performance, error diagnostics, HEC-RAS output, simulation results, warnings, convergence, instability, time step, iteration.

Parses and modifies HEC-RAS plain text geometry files (.g##) using fixed-width FORTRAN format. Handles cross sections, storage areas, bridges, culverts, lateral structures, and Manning's n tables. Use when reading geometry files, modifying cross sections, updating roughness, extracting structure data, parsing .g## files, working with XS station-elevation data, or analyzing bridge/culvert geometry. Keywords: parse, geometry, .g##, cross section, XS, Manning's n, bridge, culvert, storage, fixed-width, lateral structure, inline weir, 2D land cover, bank stations.

Decision support for HEC-RAS execution strategy. Analyzes project inspector output to recommend which plans to run, execution mode, and optimal parameters. Provides structured execution plans with dependency ordering, prerequisite validation, and resource-aware parameter recommendations. Use when planning execution strategy, selecting execution mode, determining plan order, validating prerequisites, or optimizing parallel execution parameters. Triggers: plan execution, execution strategy, which plans to run, execution order, parallel vs sequential, compute_plan, compute_parallel, mode selection, prerequisites, dependencies, runnable plans, blocked plans, execution plan, batch strategy.

Retrieves and processes AORC precipitation data for HEC-RAS/HMS models. Handles spatial averaging over watersheds, temporal aggregation, DSS export, and Atlas 14 design storms. Use when working with historical precipitation, AORC data, calibration workflows, design storm generation, rainfall analysis, SCS Type II distributions, AEP events, 100-year storms, or generating precipitation boundary conditions for rain-on-grid models. Triggers: precipitation, AORC, Atlas 14, design storm, rainfall, SCS Type II, AEP, 100-year, rain-on-grid, hyetograph, temporal distribution, areal reduction, calibration, historical precipitation, identify storm events, storm event extraction, apply temporal distributions, DSS export.

Analyze spatial variability of NOAA Atlas 14 precipitation frequency estimates within HEC-RAS model domains using intelligent extent-based downloading. Use before rain-on-grid modeling to decide whether uniform rainfall is valid, especially for large domains, multi-event comparisons, and engineering reports. Calculates min/max/mean/range statistics within 2D flow areas or project extents using NOAA CONUS NetCDF with HTTP byte-range requests. Triggers: atlas 14 variance, atlas14 variance, precipitation variance, spatial variance analysis, uniform rainfall, spatially variable rainfall, rain-on-grid variance, atlas 14 grid, atlas14 grid, noaa atlas 14 conus, precipitation frequency grid, assess uniform rainfall, extent-based precipitation, 2d flow area precipitation, Atlas14Grid, Atlas14Variance, range percentage, CONUS NetCDF.

Automated geometry repair using RasFixit and quality validation using RasCheck. Handles blocked obstructions, generates before/after visualizations, and creates audit trails. Use when fixing geometry errors, repairing obstructions, validating models, or ensuring FEMA compliance. Triggers: fix, repair, geometry, blocked obstruction, validate, check, RasCheck, RasFixit, FEMA, quality assurance, QA, overlapping, obstruction overlap, elevation envelope, geometry error.

Legacy Claude-only provider-mixed review workflow using Opus, Gemini, Codex, and Kimi K2.5. Each reviewer writes findings to separate markdown files, then orchestrator synthesizes. Use only when the user explicitly requests triple review, quad review, multi-model review, Gemini, or Kimi. Do not trigger for generic QAQC, quality assurance, security review, bug investigation, or critical review requests. Triggers: triple review, quad review, four model review, multi-model analysis, provider-mixed review, kimi review, gemini review, togetherai review

Complete USGS gauge data integration workflow from spatial discovery to model validation. Handles gauge finding, data retrieval, matching to HEC-RAS features, boundary condition generation, initial conditions, real-time monitoring, and validation metrics (NSE, KGE). Use when working with USGS data, NWIS gauges, generating boundaries from observed flow, calibrating models, validating with observed data, or setting up operational forecasting. Triggers: USGS, NWIS, gauge, streamflow, observed data, boundary condition from gauge, calibration, validation, NSE, KGE, spatial discovery, gauge matching, real-time monitoring, initial conditions, GaugeMatcher, UsgsGaugeSpatial, RasUsgsCore, flow data, stage data, discharge, rating curve, observed flow, gauge near model.