vibeflow-freecad

name	vibeflow-freecad
description	Use when creating, editing, validating, importing, exporting, or developing VibeFlow/VibeCAE geometry workflows with FreeCAD or FreeCADCmd, including interactive CAD handoff, scripted parametric CAD, STEP/STL/FCStd exchange, geometry repair, FreeCAD macro/workbench development, and traceability back to 0-caseDict/caseDict.

VibeFlow FreeCAD

This skill is responsible for using FreeCAD as the geometry modeling and CAD exchange backend for VibeCAE. It covers both usage mode and development mode.

• Usage mode: generate, edit, import, export, and validate FreeCAD geometry from 0-caseDict/caseDict.
• Development mode: develop FreeCAD scripts, macros, workbench integrations, import/export adapters, or geometry repair tools.

When to Use

• The current geometry route explicitly selects FreeCAD.
• Interactive CAD editing, sketch/feature-tree modeling, FCStd files, or scripts executed with FreeCADCmd are needed.
• STEP, BREP, IGES, STL, OBJ, or similar files need to be imported into FreeCAD for inspection or repair.
• Geometry needs to be exported from FreeCAD for backends such as Gmsh, OpenFOAM, CalculiX, Code_Aster, or Elmer.
• FreeCAD Python API, macro, workbench, or headless batch-processing issues need to be handled.

First Decide: Usage Mode or Development Mode

• If the task only generates, repairs, or exports geometry in the current case: use usage mode.
• If reusable FreeCAD modules, macros, workbenches, import/export plugins, or Studio integration are needed: use development mode.
• If FreeCAD commands are unavailable or GUI/Qt/plugin paths are abnormal: switch to vibeflow-toolchain first.
• If geometry will be meshed after generation: hand off to vibeflow-mesh or the corresponding solver skill.

What to Read First

• geometry, regions, interfaces, mesh, and execution in 0-caseDict/caseDict
• references/freecad-playbook.md
• references/freecad-practical-tips.md: software knowledge base, key concepts, failure interpretation, and adapter design points.
• Existing A-geo/geometry.py, A-geo/freecad.py, and A-geo/*.FCStd
• A-geo/exports/ and A-geo/logs/
• If developing a plugin, also read the current UDF/ or Studio integration code

Inputs

• 0-caseDict/caseDict
• FreeCAD scripts, macros, FCStd files, or external CAD files
• Reference geometry, images, dimension tables, public data, or user sketches

Outputs

• A-geo/freecad.py or the selected FreeCAD generation script
• A-geo/model.FCStd
• Exchange files such as A-geo/exports/*.step, *.stl, and *.brep
• A-geo/geometry_manifest.json
• A-geo/geometry_validation.md
• A-geo/logs/freecad_*.log

Recommended Structure

A-geo/
├── freecad.py
├── model.FCStd
├── imports/
├── exports/
├── logs/
├── preview/
├── geometry_manifest.json
└── geometry_validation.md

Usage Mode Workflow

1. Read geometry objectives, units, dimensional parameters, regions, boundary naming, and export requirements from caseDict.
2. Confirm that FreeCAD is the currently selected geometry backend; if not, do not bypass the existing CadQuery/Gmsh workflow.
3. Write or update A-geo/freecad.py so it can run headlessly.
4. Execute the script with FreeCADCmd and output FCStd plus exchange files.
5. Perform basic validation on exported files: existence, body/face counts, boundary names, units, closure, and re-import.
6. Write artifacts, assumptions, failures, and repair records back to the geometry status or error records in caseDict.
7. If the geometry is mesh-ready, hand it to the mesh skill; if geometry ambiguity remains, return to case-dict or user clarification.

Development Mode Workflow

1. Define the development target: macro, script library, import/export adapter, workbench, Studio invocation bridge, or geometry repair tool.
2. Write development notes first, recording the FreeCAD version, module dependencies, API entry points, run method, and validation examples.
3. Keep scripts capable of running headlessly, and avoid depending only on GUI interaction state.
4. Pass paths from the case root, environment variables, or script arguments; do not hard-code local machine paths.
5. Smoke-test import/export behavior, validating at least one simple solid and one target-case solid.
6. If the development result becomes a reusable capability, place it under UDF/ or the corresponding Studio module; the current case should record only the invocation method and artifacts.

Core Rules

• caseDict is the source of truth for geometry intent and parameters; the FreeCAD file is not the sole source of truth.
• FreeCAD scripts must tolerate FreeCADCmd's special handling of arguments; use parse_known_args() when needed.
• Output paths must be anchored to the case directory and must not depend on the current working directory.
• Prefer STEP/BREP for exact CAD exchange; use STL only for triangulated surface exchange.
• Face, body, region, and patch names that matter to downstream solvers must be recorded in the manifest.
• Do not automatically overwrite an FCStd file manually edited by the user unless the task explicitly asks for a rebuild.

Validation

• FreeCADCmd or an equivalent command can run.
• The script executes without a traceback.
• Target exported files exist and are non-empty.
• STEP/BREP/STL can be re-imported.
• geometry_manifest.json records exported files, units, object names, and backend.
• geometry_validation.md states whether the geometry can enter the meshing stage.

Fallback Rules

• Geometry requirements are unclear: return to vibeflow-case-dict
• FreeCAD environment is unavailable: return to vibeflow-toolchain
• Meshing fails but the geometry is valid: hand off to vibeflow-mesh
• A downstream backend needs a specific format: hand off to the corresponding solver skill