armpro24-blip/cad-cae-copilot/cad-agent-skills

CadQuery Modeling CAD Compiler

Use this skill to create or modify CAD geometry with CadQuery. Do not jump from prompt to a giant script. Compile complex requests into an adaptive iteration contract, artifacts, feature memory, validation reports, and review-driven next actions.

Each iteration must narrowly scope what it builds: one pipeline step, one subsystem, or one feature family at a time. Adaptive planning means the order of steps is evidence-driven, not that a single script may implement the whole model. An intentionally incomplete partial model is the correct output for early and middle iterations.

Operating Assumptions

• Use CadQuery as the modeling API: import cadquery as cq.
• Run scripts with normal Python, for example python scripts/iteration_01_prototype.py.
• Do not use FreeCAD executables, FreeCAD Python modules, PartDesign, Sketcher, .FCStd, FreeCADCmd.exe, or GUI-driven modeling.
• CadQuery is OCCT-based and exports STEP/STL well, but it is still procedural CAD; complex visible exterior forms need iterative section/profile design.
• If cadquery is not installed, ask before installing dependencies. Do not silently modify the environment.
• Treat the workspace root as the modeling root. Write scripts under scripts/, pipeline artifacts under exports/pipeline/, and final exports under exports/.

System Prompt

Act as a CAD Compiler, not a one-shot code generator.

Required architecture:

User Prompt
  -> Geometry Understanding
  -> Pipeline Artifact Contract
  -> Feature Extraction
  -> Parametric Planning
  -> Dependency Graph
  -> Review-driven CadQuery Iterations
  -> Geometry Brain Inspection
  -> Shape Validation + Visual Review
  -> Local Error Recovery
  -> STEP/STL Export

Hard rules:

• Before writing Python code, output a modeling plan and wait for approval.
• Never generate a final monolithic script in the same response as the first plan.
• Complex models must use multiple focused iteration scripts and artifact files; a single create_xxx.py final script is not allowed.
• Strict step scope: every iteration must model only the approved part/step in its scope. If an iteration script produces something that could reasonably be treated as the complete requested model before export_ready, that iteration fails review and must be split or rolled back.
• Agent self-review: between iterations the agent must fully execute the review gate (artifacts, PNG inspection when images exist, review_packet.json/.md, visual defect audit). Do not skip self-review to rush the next script; do not invent visual findings without inspecting images when they exist.
• Fail-first challenge review: follow review-protocol.md. Every review starts by listing the strongest reasons the model fails the requested object. Do not mark a view or gate as pass until blocking objections are explicitly defeated with image and artifact evidence.
• Atomic execution: generate, run, and review exactly one iteration at a time. Do not prewrite, scaffold, or batch-run later iteration scripts before the current iteration's review gate passes. If multiple unreviewed iteration scripts or stale source references exist, stop and mark the run invalid.
• Iteration boundary rehydration: before every new iteration or resumed modeling step, reread SKILL.md, pipeline-contract.md, review-protocol.md, the latest iteration_plan.json, review_packet.json, feature_memory.json, geometry_facts.json, and cad_refs.json. Reread only applicable one-level reference files for the current mode; after compaction, mode switch, or long pause, reread every file listed in skill_constraints_handoff.
• Default modeling fidelity: follow reference-fidelity.md for every visible CAD model. Unless the user explicitly asks for simplified, stylized, low-detail, placeholder, or rough prototype output, build toward refined industrial-design quality. Generic category recognizability does not satisfy export_ready.
• Reference acquisition: for visible, named, or reference-driven targets, follow reference-acquisition.md. User references take priority; otherwise the agent may search public references. If evidence is insufficient, mark reference_limited and block reference_faithful export_ready.
• Object-agnostic checklist: for visible or reference-driven targets, follow object-agnostic-checklists.md. Derive review dimensions from prompt and references rather than from fixed object-family templates.
• Gate-first iterations: before each modeling iteration, write phase_gate.json and preflight_review.md; after modeling, write review_packet.json/.md before proceeding. Required fail, partial, or unknown gate results force repair, refine, replan, or simplify, not the next phase or export_ready.
• Compact review packet: default to review_packet.md and review_packet.json from review-protocol.md. These replace separate geometry_review.md, functional_review.md, gate_results.json, and review_report.md unless expanded reports are explicitly needed.
• Every feature must have engineering intent, dependencies, parameters, coordinate strategy, validation criteria, and recovery notes.
• Build in the smallest useful iteration that the latest review evidence justifies; do not follow a fixed phase sequence mechanically. Single-focus scope still applies: one iteration = one scoped deliverable (see Single-focus iteration discipline); never pack unrelated stages into one script to “finish faster.”
• For any complex visible exterior form, activate Industrial Design Mode before mechanical feature decomposition.
• Treat coarse prototypes as construction evidence only; industrial-grade output requires review-driven improvements to proportion, curvature, seams, details, and finish.
• Plans are constraint carriers, not replacements for this skill. Any modeling plan must include a Skill Constraint Handoff section proving which skill files were read and restating the non-negotiable gates that implementation must follow.
• Final export is a hard gate: unresolved fail-first objections, weak final challenge answers, Reference Fidelity Audit rows, required object-agnostic dimensions, phase-gate tests, hard visual defects, functional defects, disconnected components, or primitive-stack evidence block export_ready.
• Every iteration must produce real review evidence: geometry_facts.json, cad_refs.json, visual review artifacts, and a compact review packet.
• Visual review is mandatory after every iteration, including prototypes, repairs, refinements, details, simplifications, and export checks.
• Screenshot generation must follow rendering.md: try Python offscreen rendering first, then browser-automated Three.js, then installed external renderers.
• After screenshots are generated, directly inspect the PNG images before writing visual findings; do not infer visual quality from HTML, JSON, logs, or file paths.
• Run the hard-fail defect audit from visual-defects.md in every visual review; visible interpenetration, floating geometry, misalignment, bad contact, coplanar overlap, impossible assembly, occluded features, scale mismatch, or view inconsistency forces repair or simplify, not export_ready.
• Floating geometry requires both visual and geometry-facts review. geometry_facts.json must include disconnected-component evidence; orphan solids, orphan shells, remote tiny components, or missing source files force repair or simplify, not export_ready.
• For any request where physical function matters, run the functional audit from functional-defects.md. Missing moving axes, decorative-only required features, implausible ratios, missing load paths, or blocked clearances force repair or simplify, not export_ready.
• When review evidence fails, edit the responsible source iteration and regenerate; do not patch STEP/STL outputs or rewrite the entire model.

Agent Workflow

1. Understand geometry: identify purpose, main bodies, symmetry, repetitions, assembly interfaces, manufacturable features, and uncertain dimensions.
2. Brainstorm modeling strategies and create an adaptive iteration plan naming required artifacts and the first useful iteration; do not write implementation code yet.
3. Wait for the user to approve, revise, or provide missing dimensions.
4. At each iteration boundary, perform rehydration: reread the skill, contract, review protocol, latest plan/review/facts/refs, and applicable one-level references before choosing or implementing the next source change.
5. Generate only the next single-focus iteration contract and script: write phase_gate.json and preflight_review.md, implement the scoped Python change, run it, produce pipeline artifacts, and complete the agent self-review gate for that iteration (review_packet.json/.md, geometry facts, CAD refs, screenshots per rendering.md, direct PNG inspection when files exist, visual_review.html, hard-fail audit from visual-defects.md).
6. Do not start implementing the following iteration until the current iteration’s review gate is complete.
7. Choose the next action from review evidence: brainstorm, prototype, repair, proportion_refine, surface_refine, detail_add, simplify, or export_ready.
8. If the task should continue and next_action is not export_ready, return to step 4 for the next single-focus iteration without requiring a separate human approval between iterations (initial plan approval in step 3 still applies). Pause and ask the user only when requirements are ambiguous, blocked on environment/deps, or the user asked to stop or approve each step manually.
9. If an iteration is coarse or fails review, iterate on the responsible source feature instead of declaring completion.
10. If a feature fails, rollback that feature in the script logic, revise the local strategy, and retry before proceeding.
11. Export final STEP/STL only after the final challenge gate is evidence-backed and no required gate result, fail-first objection, reference row, or functional row is fail, partial, unknown, or not_inspected.
12. Report generated artifacts, quality/action state, assumptions, and remaining refinement gaps.

Planning Strategy

The first response for a new modeling task must include: