physpace/simplecadapi/skill

SimpleCAD SDK Skill

This file is the router: it owns load order, route selection, and execution discipline only. Each selected workflow owns its procedure. Classify the request, load exactly one workflow, follow its domain and discipline references, and read exact API pages for the APIs its steps use.

Mandatory load order

Paths are relative to this file's directory.

1. Read this file.
2. Select exactly one workflow from Task routing. If two rows

plausibly match, ask one discriminator question that names the candidate outcomes; never pick silently between routes with different deliverables.

1. Read the selected workflow in full. From selection on, it owns the

procedure; do not load another workflow's procedure.

1. Load each required domain/discipline file the workflow names

before the step that uses it; optional ones only when their trigger fires.

1. Before the first call of any API, read its exact page

(references/docs/api/<name>.md, references/docs/stdlib/<name>.md, references/docs/core/<type>.md). A method absent from its page does not exist, however plausible it looks.

• You MUST NOT read the full API or stdlib index up front; the workflow

names every page its steps need.

• Routing questions are decided here; after selection the workflow owns

execution. You MUST always follow the global rules and execution discipline below.

• Questions about an existing STEP file that change nothing enter no

workflow; you MUST use references/domains/step-inspection.md for them directly.

• A person who has the code-first editor open (sca edit) and talks

about what they selected, a cell they copied, or a value they tuned enters no new workflow: the modeling follows the workflow you selected, and you MUST read references/domains/editor-collaboration.md first to see what they see (selection cell, sca snapshot, cell references) and how to hand the work back. While the editor runs, sca cell is the only way to change a regular cell; edit the file only when no editor is running, or for the setup / @app.function cells sca cell refuses: the editor is the file's writer.

• Creating, installing, updating, or removing a SimpleCADAPI addon (a

third-party skill+tooling package around .scadpkg) enters no workflow; you MUST use references/domains/addon-development.md directly.

Task routing

Read exactly one workflow first, per the user's goal:

Do not present route-choice menus when a row already matches: profile, strategy, and tool choices inside a route belong to that workflow's own gates, not to an up-front question. A missing prerequisite — state it and stop that route; never invent an alternative route.

Routing discipline

Global rules (every task)

1. Refine the requirement into a brief before modeling

(references/domains/requirement-refinement.md).

1. Use keyword arguments for every documented public API and

stdlib function, except the canonical durable export call capture(result, path), whose two required arguments are positional.

1. Every model is a marimo notebook with a [tool.simplecadapi]

header (references/docs/guides/notebook-runtime.md): one part per notebook; one assembly notebook per product, composing children with scad.use(...); parameters live in the notebook that consumes them; exposed tunable parameters are var()/Var declarations (optionally with unit, tolerance). Part sources follow the Feature Tree Convention (references/discipline/feature-tree-convention.md): block structure sketch → basic body op → bool → modifier, one feature per block and one block per cell, with a mandatory boundary comment # ---- feature: <slug> (<role>) ----; 2D profiles and planar paths go through the sketch API, primitives only when the shape is completely contained in the basic form. Where the cell boundaries go and which numbers are a var() follow references/discipline/notebook-cell-design.md: read it with the convention before writing any notebook; it states each rule with its reason and the error you get when you break it.

1. Booleans (union_rsolid, cut_rsolid, cut_rsolid_list, intersect_rsolid)

accept mixed inputs and return exactly one Solid; union defaults to glue=False with a conservative scale-relative tolerance and fails explicitly when it cannot produce one merged solid.

1. Build and validate incrementally: each major step prints small

QL-derived facts; grounding uses QL wherever possible; never print whole solids or full model objects.

1. Topology enumeration is QL-only and strictly enforced: plural

getters (get_edges, get_faces, get_wires, get_vertices, get_solids, get_inner_wires) accept ONLY an index — the no-argument list form raises. Enumerate, count, and measure via ql.<kind>().resolve(shape); filter with QL predicates plus take/exactly cardinality; never build selections by looping over an enumerated list and indexing it. Indexed picks (get_edges(index)) are reserved for intentional, named choices and are recorded as graph selection nodes.

1. Tags: attach with apply_tag(shape=..., tag=...) (LOCAL scope —

it never propagates downward); inspect with list_tags(shape=...); keep numeric facts in metadata, never in tags.

1. The notebook file is the only source of truth; .scadpkg is

generated from it for exchange and publishing (sca run product.py --out out/product.scadpkg, or capture(result, "out/product.scadpkg") in one call) and is never read back as a source. @scad.part / @scad.assemble are for reusable library parts in plain modules; they may be called inside a notebook cell.

1. simplecadapi.inspect.brep and simplecadapi.inspect.drawing are

diagnostic-only and rejected inside GraphSession; obtain/export geometry first, inspect outside.

1. Standard parts first: before hand-modeling a gear, ring gear,

rack, cycloidal disc, or bearing, check scad.std.gear / scad.std.bearing.

1. Read references/docs/guides/notebook-runtime.md in full

before writing a notebook, composing notebooks, or reasoning about the cell cache. Run models with sca run (sca edit opens them in the editor for a person); never enable marimo's [tool.marimo.runtime] cache_cells in the editor, and never commit the generated __marimo__/ directory.

1. Manage the modeling project the way software is managed: put the

workspace under git from the first file, commit at verified milestones (a passed verification, not a wall clock) with messages that say what changed and why, and use a branch per design direction when alternatives are on the table. Generated state — __marimo__/, .sca-editor/, out/ — belongs in .gitignore, never in a commit.

Boundaries

• .scadpkg is the canonical durable product; STL/OBJ/MJCF are

point-in-time exports, never editable sources.

• Model JSON is the replay/interchange contract for explicit

GraphSession flows; never hand-author payloads.

• No claims of strength, fatigue, thermal, vibration, tolerance

compliance, or regulatory fitness without the corresponding analysis actually run.

Execution discipline (every task)

1. Gates bind artifacts: a validation gate passes only when its named

artifact exists — printed QL facts, targeted measurements, named rendered views, completed brief fields. A stated feeling of success is not a gate result.

1. Blocking waits: an Ask-or-Record blocking item resolves before any

geometry — asked once (batched into one question set) or recorded as an explicit assumption. Proceeding with neither is the failure, not the asking.

1. Serial phases: do not preload later-phase pages or build

later-phase artifacts early. After an interruption, re-ground from the owning artifact (source file, brief), not from conversation memory.

1. Repair the owning source: the named parameter, the brief field, or

the upstream selection — never the downstream symptom. Candidate x parameter enumeration loops are diagnosis debt, not repair (references/discipline/failure-and-repair.md).

1. A failed check closes by changing the design or by redefining the

check with the user — never by weakening or deleting the check.

Example SDK usage

import simplecadapi as scad
from simplecadapi import GraphSession, export_model_json, replay_model_json
with GraphSession(graph_id="box") as session:
    shape = scad.make_box_rsolid(width=10.0, height=20.0, depth=30.0)
    session.capture_result(value=shape)
    payload = export_model_json(session=session)
rebuilt = replay_model_json(json_str=payload)
print(len(rebuilt))

References

• references/README.md — skill layer structure
• references/workflows/ — goal-oriented workflows, including drawing reconstruction
• references/domains/ — capability domains, including drawing inspection
• references/discipline/ — modeling knowledge and invariants
• references/discipline/verifier-scripts.md — writing a verifier script (OCP through simplecadapi.verify)
• references/SDK_OVERVIEW.md — package-level map
• references/inspect/brep-reverse-engineering.md
• references/domains/addon-development.md — sca addon CLI and authoring guide
• references/domains/editor-collaboration.md — working with a person in sca edit:

selection cell, snapshot, cell references, sca cell / sca new, parameters

• references/docs/guides/reconstruction-agent-test-prompt.md
• references/docs/guides/reconstruction-agent-strategy.md
• references/docs/guides/notebook-runtime.md
• references/ql-playbook.md
• references/scadpkg-format.md — .scadpkg consumer spec: member

layout, tag channel, minimal readers (addon exporters read this)

• references/docs/api/, references/docs/stdlib/, references/docs/core/