Cad sim tooling research scout

CAD Sim Tooling Research Scout

Use this skill to choose the smallest useful capability for the current project. It can recommend viewers, annotators, CAD kernels, CAD authoring tools, meshers, simulators, optimization libraries, GPU frameworks, browser/computer-operated apps, commercial tools, datasets, reference CAD, standards, or datasheets.

Keep PYTHONPATH=<run-root> python -m viewer3d serve <run-root> as the stable default review surface. Never assume a viewer3d executable exists on PATH. The scout adds freedom in tool choice; it does not remove the need for compact evidence, permissions, source boundaries, reviewer-readable outputs, and honest claim limits.

Use a separate tooling-scout thread when the workflow can launch one and the tool choice materially shapes the first design or review surface. Examples: simulation/optimization-heavy projects, unfamiliar domains, commercial or GUI simulators, CAD-kernel/tool comparisons, and cases where assembly motion or retention paths are the main uncertainty. A local inline scout note is fine for ordinary lightweight decisions; record the topology either way.

Also use the scout as a stage-entry tooling scout before an approved new stage when tool choice could affect quality, evidence, cost, feasibility, or the user-facing handoff. Examples: printability/support-material optimization, major design optimization, FEA/CFD/model-fidelity expansion, robotics integration simulation, production-grade website/evidence-export work, or a commercial/GUI tool stage. The scout may recommend that the default stack is enough. It must not start an unapproved stage, accept licenses, spend money, install large tools, upload private files, or run long/cloud/GPU jobs unless the brief or a user answer has already approved that step.

When a reviewer is unsure whether the current tools can support an A_plus_builder_handoff, prefer a separate tooling-scout thread. The scout should recommend the smallest better way to make the primary guide reviewable, such as annotated renders, a CAD-backed stepper, glTF/Three.js assembly states, CAD inspection, simulator playback, screenshots/video from an external tool, or a lightweight analysis/visualization workflow.

When the project uses a primary evidence container or website-first handoff, prefer tools that can export evidence the Meta-Agent can embed directly in that surface. Raw files are still useful for audit/download, but the scout should ask whether the tool can produce screenshots, plots, videos, glTF/HTML, CSV-derived tables, static reports, simulator result images, local-server views, or other web-readable outputs that make the evidence visible at point of use.

Also use the scout when a critical design decision cannot be evidence-closed with the current reset stack. Examples: a retention feature needs a force-path view, a hull choice needs hydrostatic/drag evidence, a robot stability claim needs a CG/tipover check, a thermal path needs a quick estimate, or an optimization winner needs a fair baseline/sweep. Choose the smallest useful evidence tier; do not jump to heavy solvers or commercial tools unless the claim and permissions justify them.

Also use it when design-space confidence is the blocker: the current handoff does not make the selected design feel like the best current option, and a different viewer, CAD inspector, plotting/export tool, simulator, optimization surface, or interactive evidence container could compare plausible alternatives more convincingly.

Also use it when minimum viable alternative evidence is the blocker: the reviewer needs one compact alternative sketch, CAD-backed variant, staged comparison, calculation/simulation result, or embeddable export to challenge the selected design, and the current stack makes that artifact awkward or unclear.

Also use it when Exemplar-Calibrated Handoff is the blocker: the reviewer cannot pass a visual-only, state-transition, design-delta, evidence-maturity, diagnosis, or boundary test with the current viewer/report surface. Prefer the smallest tool or export path that produces reviewable evidence: same-basis screenshots, videos, glTF/HTML, plots, scenario dashboards, CAD-backed staged views, diagnostic logs, or simulator exports.

Also use it when Verifier-Backed Spatial Evidence is the blocker: the Meta-Agent needs generated guards or checks plus embeddable 3D/CAD/plot visualizations for a spatial, state, motion, clearance, connection, scenario, or interface claim. Prefer tools that can produce both machine-readable verifier results and reviewer/user-readable evidence for the primary surface.

Also use it when a Quality Harness row in quality/quality_harness.yaml is missing or fail because the current stack cannot produce convincing verifier evidence or primary-surface evidence. The scout recommendation should name which row it can close, what artifact it would export, whether the artifact can be promoted into the primary surface, and whether the remaining gap is instead a physical_boundary, user_boundary, or stage_approval.

Inputs

Before recommending tools, read only the project-local or explicitly allowed inputs needed for the tooling decision:

• intake/project_brief.yaml, especially autonomy_envelope, external_capability_policy, analysis_intent, analysis_envelope, and stage_frontier;
• current handoff.json, canonical annotation_view/, review packet, or simulator/analysis notes when they exist;
• the reviewer, Meta-Agent, or user question that triggered the scout;
• the approved stage name, scope, constraints, and ask-before rules when this is a stage-entry scout;
• allowed web or local sources under the active source boundary.

If the source boundary or external capability permission is unclear, route needs_user_approval or blocked_boundary rather than researching around it.

Research Method

Use current primary sources when tool choice depends on current availability, license, install method, compatibility, or maintained features. Prefer official docs, repositories, package pages, papers, vendor docs, or project websites.

Evaluate candidates against:

• whether the tool answers the actual project uncertainty;
• whether Codex can drive it through CLI, API, Browser, computer use, or a documented GUI workflow;
• agent operability as a named criterion: prefer deterministic MCP, API, CLI, or headless surfaces with typed or structured inputs/outputs, persistent inspectable state, stable identifiers, incremental build-render-measure- diagnose-revise-validate-export loops, machine-actionable errors, bounded retries, reconstructive text source, reproducible versions/commands, clear permission boundaries, and machine-readable evidence. A powerful GUI with no reliable control or export loop is weaker for agent work than its feature list suggests;
• inputs and outputs it can exchange with the reset packet;
• whether it can export compact embeddable evidence for the primary handoff surface, not only raw project files;
• what Evidence Promotion path it enables: screenshot, plot, video, glTF/HTML, CSV-derived table, notebook/report export, local-server embed, or other web-readable evidence the Meta-Agent can place directly in the primary handoff;
• whether it can expose design-space tradeoffs or selected-design confidence with screenshots, plots, staged views, videos, tables, widgets, or simulator exports;
• whether it can produce the smallest useful alternative-evidence artifact, rather than only polishing the selected design explanation;
• whether its outputs help the primary surface pass Exemplar-Calibrated tests: visual-only, prose-only, state-transition, design-delta, choice-invisibility, driver-trace, evidence-maturity, diagnosis, and boundary checks;
• whether it can generate or export Verifier-Backed Spatial Evidence: measurements, clearance checks, connected-component checks, retained-object path checks, protected-volume checks, assembly state checks, collision/reach/wiring/service envelopes, scenario/sensitivity checks, or other compact verifier artifacts with embeddable 3D/CAD/plot/video evidence;
• whether it can close one or more Quality Harness rows by producing quality_harness_results.json-backed evidence and a compact primary-surface artifact rather than only support-file proof;
• license, cost, credentials, upload/privacy, install size, runtime, GPU/cloud needs, and maintenance burden;
• fidelity limits and the claims the evidence can or cannot support.

Useful candidates to consider when relevant, not as defaults:

• viewer3d layers/states or a small Three.js/glTF stepper for CAD-backed staged assembly, exploded views, strap/latch paths, tool access, removal sequences, or first-test walkthroughs;
• CascadeStudio or OpenCascade.js for browser-native OCCT CAD, STEP/STL import, selectors, measurements, and agent-controllable CAD workflows;
• Mayo or CAD Assistant-style tools for CAD inspection, conversion, assembly trees, properties, clip planes, and screenshots;
• build123d, CadQuery, or MCP tooling for scriptable BREP authoring and geometry feedback;
• Gmsh, SALOME, VTK.js, ParaView/Glance, or domain solvers for meshing, pre/post-processing, and scalar/vector/tensor result visualization;
• Isaac Sim, MuJoCo, PyBullet, Gazebo, Warp, custom CUDA/Mojo/Python kernels, or commercial simulators for robotics, physics, controls, GPU simulation, or specialized domains.
• browser-streamed GUI adapters such as noVNC, Apache Guacamole, Omniverse WebRTC, or vendor web viewers only when a GUI-only tool is the smallest useful path. Treat the stream as an operating surface, not the durable evidence: export screenshots, videos, meshes, result files, commands, or a compact replay note for reviewer inspection.

Output

Write a compact recommendation when the run root is writable:

tooling/tooling_scout.md

Use this shape:

route: use_default_stack # use_default_stack | use_tool_now | defer_tool | needs_user_approval | no_extra_tooling | blocked_boundary
scout_topology: inline_meta_agent # inline_meta_agent | separate_tooling_scout_thread | local_probe_allowed
trigger: "why the scout ran"
stage_entry:
  active: false
  stage_name: null
  approved_scope: []
  ask_before_rules: []
recommended_next_tool: "viewer3d/CascadeStudio/Mayo/Gmsh/etc. or null"
why_this_tool: "smallest useful reason"
tools_considered:
  - name: "..."
    source: "url, package, docs, or local command"
    fit: "strong | possible | weak | not_for_now"
    reason: "..."
permission_or_stop:
  status: "allowed | ask_first | forbidden | unclear"
  needed_user_approval: []
adapter_contract:
  launch_or_run: []
  inputs: []
  outputs: []
  primary_review_surface: "viewer3d | assembly_stepper | simulator_view | external_gui_stream | other"
  embeddable_evidence_outputs:
    - "screenshot | plot | table | video | gltf | html | csv_summary | static_report | local_server_view | none"
  exemplar_calibrated_evidence_outputs:
    - "visual_only | state_transition | design_delta | driver_trace | evidence_maturity | diagnosis | boundary | none"
  verifier_backed_spatial_evidence_outputs:
    - "measurement | clearance_check | connected_component_check | retained_object_path | protected_volume | assembly_state | scenario_sensitivity | collision_reach_wiring | plot | 3d_view | video | none"
  embed_or_export_steps: []
  reviewer_can_inspect: []
  marks_or_results_location: []
  durable_evidence_required: []
  raw_files_for_audit_or_download: []
agent_operability:
  preference_from_brief: "programmatic_first | balanced | capability_first"
  interface_tier: "mcp | api | cli | headless | browser | gui_automation | manual_only"
  incremental_feedback_loop: "strong | partial | weak"
  persistent_state_and_stable_ids: "strong | partial | weak"
  machine_actionable_errors_and_recovery: "strong | partial | weak"
  reconstructive_source_and_versioning: "strong | partial | weak"
  headless_reproducibility: "strong | partial | weak"
  permission_and_sandbox_fit: "allowed | ask_first | forbidden | unclear"
  evidence_export_fit: "strong | partial | weak"
claim_limits: []
next_action: "what the Meta-Agent or reviewer should do next"

Use normal Markdown around the YAML-like block when that is clearer. Keep it short enough for a reviewer to read quickly.

Create tooling/manifest.yaml only if a tool is actually used, installed, downloaded, scripted, licensed, browser/computer-operated, or produces durable files/results. Do not create it for ordinary research notes or a recommendation that keeps the default stack.

Routing

• use_default_stack: the seeded PYTHONPATH=<run-root> python -m viewer3d serve <run-root> module and existing reset artifacts are enough.
• use_tool_now: an allowed tool should be used before user review.
• defer_tool: a tool may help later, but current evidence is enough.
• needs_user_approval: the next useful step needs money, license acceptance, credentials, private upload, large install, long/cloud/GPU job, side-effecting GUI operation, or an ask-first policy.
• no_extra_tooling: no materially useful tool opportunity was found.
• blocked_boundary: the scout cannot proceed without a clean source boundary or permission state.

The scout chooses tools; it does not judge the product design. The reviewer decides whether the resulting evidence is sufficient.

Review Loop Use

Run this skill at checkpoints, not every loop:

• after grill and before first design when the project is tool-sensitive;
• before entering an approved new stage when tool choice could materially affect stage quality, evidence, cost, feasibility, or evidence export;
• before maturity promotion when better tooling may avoid likely user nudges;
• when reviewer evidence is insufficient for geometry, physics, simulation, optimization, robotics behavior, or user workflow critique;
• when the primary builder guide cannot reach the requested grade with the current viewer, static renders, or hand-authored HTML alone;
• when a primary evidence container exists but readiness-critical evidence is only linked as raw files instead of embedded or summarized at point of use;
• when the reviewer reports critical_design_decision_evidence_status: continue_autonomous and the next evidence tier depends on better tooling, visualization, simulation, CAD inspection, or research;
• when repeated complaints suggest the framework needs a better tool to expose the issue;
• when the user explicitly asks for better tools.

When the issue is physical sequence clarity, prefer a CAD-backed staged or animated artifact over prose or static screenshots: viewer3d states, a Three.js/glTF stepper, or another small mesh-backed surface. Use video only as supporting evidence unless the user specifically asks for a passive demo.

If a tool is selected, preserve the seeded python -m viewer3d serve command as fallback unless the reviewer explicitly agrees the chosen tool provides a better review surface for this run.