vibeflow-toolchain

name

vibeflow-toolchain

description

Use when checking, diagnosing, documenting, or separating VibeFlow/VibeCAE toolchain/environment failures from case-definition failures, including OpenFOAM bashrc and utilities, Python, virtualenv, CadQuery/OCP, Gmsh CLI/Python API, ParaView/pvpython, FreeCAD, Code_Aster, FEniCS/FEniCSx, MOOSE, LAMMPS, Scilab, SU2, FDS, Elmer, CalculiX, FreeFEM, OpenRadioss, Nektar++, OpenLB, solver commands, PATH/module issues, and stage-specific readiness before geometry, mesh, run, postprocess, or report work.

VibeFlow Toolchain

This skill is responsible for determining whether a problem is caused by the environment or by the case. It only handles toolchain, environment, path, module, and command-availability issues. Once tools are available, the problem should be handed back to the corresponding domain skill.

When to Use

• The OpenFOAM environment needs to be confirmed as correctly loaded.
• Availability of python3, cadquery, gmsh, pvpython, foamDictionary, or checkMesh needs to be checked.
• Availability of VibeCAE extension backends needs to be checked, such as FreeCAD, Code_Aster, FEniCS/FEniCSx, MOOSE, LAMMPS, Scilab, SU2, FDS, Elmer, CalculiX, FreeFEM, OpenRadioss, Nektar++, or OpenLB.
• A stage fails, but the cause may be a missing environment, polluted paths, or non-importable modules rather than caseDict itself.
• Minimal diagnostic commands, tool-version summaries, environment-fix suggestions, or error classification need to be generated.
• A toolchain error needs to be written to caseDict.errors.

What to Read First

• Current shell environment, PATH, and related environment variables.
• Tool path snapshot generated by bootstrap in AGENTS.md.
  • These paths only represent candidate entry points on the current machine, not cross-machine specifications.
  • Before use, existence and version must be revalidated.
  • Do not copy these absolute paths into general documents, skills, or caseDict.
• The caseDict block corresponding to the current task stage.
• Check items and failure classification: references/environment-checks.md
• VibeCAE backend check items: references/cae-toolchecks.md

Core Workflow

1. Determine which tools the current stage depends on.
2. Check only the minimal tool set for the current stage.
3. Classify the problem as:
   • tool missing
   • tool exists but environment is not loaded
   • tool exists and can run, so the problem is in the case or script
4. Clearly report the impact scope; do not vaguely say "the environment has a problem".
5. If it is a toolchain issue, write it to errors.entries and set stage=toolchain and category=environment.
6. If the toolchain is available, clearly hand control back to geometry/mesh/openfoam/postprocess/report.

Minimal Check Set

• caseDict / report
  • python3
• geometry
  • python3
  • Python cadquery
  • Optional Python ocp_tessellate, for high-fidelity preview support
  • Optional FreeCAD / FreeCADCmd, required only when the current geometry route selects FreeCAD or interactive CAD-related capabilities
• mesh
  • gmsh or Python gmsh
  • OpenFOAM mesh-conversion tools
• run
  • OpenFOAM bashrc
  • foamDictionary
  • checkMesh
  • Target solver
• postprocess
  • python3
  • pvpython
  • Python packages needed to read OpenFOAM results
• vibecae / selected backend
  • Check only the backend explicitly selected by the current caseDict or task
  • Structural FEM/multiphysics: Code_Aster, CalculiX, Elmer, FEniCS/FEniCSx, MOOSE, FreeFEM
  • CFD/aerodynamics/fire/spectral elements/LBM: SU2, FDS, Nektar++, OpenLB
  • Molecular/particle: LAMMPS
  • Explicit dynamics: OpenRadioss
  • Numerical scripting/control: Scilab

Outputs

• Tool-availability conclusion for the current stage
• Missing items and their impact scope
• Suggested next step: continue the current stage or fix the toolchain first
• Reproducible minimal check commands and key output summary
• Updates to caseDict.errors when necessary

Rules

• Do not write absolute tool paths into caseDict.
• Do not hard-code absolute paths from one machine into skills, templates, or general instructions, such as user home directories, package-manager installation prefixes, fixed application installation directories, or a specific ParaView extraction directory.
• Paths found by local bootstrap can only be treated as "current-machine candidate values", not product defaults.
• Do not misclassify "optional tool missing" as "the entire case cannot proceed".
• Do not block the entire project because a VibeCAE backend is not installed; it is required only when the current case explicitly selects that backend.
• Separate framework tools from application tools:
  • MOOSE is a framework; usually check the concrete MOOSE app executable rather than searching for one unified moose command.
  • OpenLB is usually a source tree and example-program build system; focus on source root, compiler, make, MPI, and example buildability.
  • FEniCS/FEniCSx mainly check Python modules rather than a single solver command.
• For tools with alternatives, explain the default path and fallback route.
• Prefer environment variables and PATH for tool discovery:
  • OpenFOAM: loaded $WM_PROJECT_DIR, $FOAM_APPBIN, foamDictionary, checkMesh
  • VibeFlow resource: $VIBEFLOW_RESOURCE_DIR
  • VibeFlow Python: $VIBEFLOW_PYTHON or python in the active environment
  • Python environment directory: $VIBEFLOW_PYTHON_ENV or a virtual environment explicitly provided by the user
  • Gmsh: $VIBEFLOW_GMSH or gmsh
  • ParaView: $VIBEFLOW_PVPYTHON, pvpython, or pvpython3
  • VibeCAE backend: first use $VIBEFLOW_<TOOL> or $VIBEFLOW_<TOOL>_*, then use PATH
• When the environment is fine, explicitly hand the conclusion to the corresponding domain skill instead of staying at the toolchain layer.
• Do not proactively modify system environment, global packages, permissions, or shell configuration. Ask the user for confirmation before high-risk operations.
• Check commands should be read-only, lightweight, and repeatable.

General Tool Discovery Order

1. First check whether the current shell already provides the tool: command -v <tool>, <tool> --version, and necessary Python import.
2. Then check VibeFlow/VibeCAE conventional environment variables, such as $VIBEFLOW_PYTHON, $VIBEFLOW_PYTHON_ENV, $VIBEFLOW_RESOURCE_DIR, $VIBEFLOW_PVPYTHON, $VIBEFLOW_GMSH, $VIBEFLOW_OPENFOAM_BASHRC, and each backend's $VIBEFLOW_<TOOL> entry in references/cae-toolchecks.md.
3. Then refer to the "current-machine path snapshot" from AGENTS.md or Studio bootstrap output, verifying each path's existence.
4. Only then provide local-system fix suggestions, such as sourcing the OpenFOAM bashrc, activating a Python venv, installing Gmsh, installing ParaView, or configuring PATH.

Use placeholders rather than concrete machine paths in command examples:

<OPENFOAM_BASHRC>
<VIBEFLOW_PYTHON_ENV>
<VIBEFLOW_RESOURCE_DIR>
<PVPYTHON>
<GMSH>
<FREECAD_CMD>
<CODE_ASTER_RUNNER>
<MOOSE_APP>
<LAMMPS>
<SU2_CFD>
<FDS>
<ELMER_SOLVER>
<CALCULIX_CCX>
<OPENRADIOSS_STARTER>
<OPENRADIOSS_ENGINE>
<NEKTAR_SOLVER>
<OPENLB_ROOT>