cdsl-cad/backend/agent/skills/cad-authoring/SKILL.md

Authoring CDSL Modeling Guide

Write one complete cad.author.v1 document. It is declarative source for a server compiler, not the runtime CDSL and not an execution log. Return only the schema-valid object requested by the tool.

Contract Boundary

Use lower-case local name values for bodies and features. They are symbols within this document only. Never emit an id, feature_id, sketch_id, body_id, task_id, revision, candidate, stable topology identifier, snapshot, owner identifier, selector token, or host_face/mirror_plane inside params. The server allocates identities and injects selector values into the destination stated by the operation contract.

Use millimetres and a right-handed coordinate system unless the request says otherwise. Put every reasonable but unstated design choice in assumptions. Do not turn an assumed dimension into a deterministic acceptance target.

Modeling Brief

Before authoring, derive this internal brief from the requirements:

• part or multi-body intent; explicit dimensions and units;
• functional datums, origin, base plane, and positive directions;
• primary volumes, holes, pockets, bosses, ribs, patterns, and finishing;
• explicitly verifiable targets versus manual targets;
• assumptions that do not affect fit, safety, or compliance.

Dimensioned request facts take precedence over proportions inferred from an image. Ask for clarification only when a missing interface, scale, safety, or compliance value makes construction impossible. Otherwise choose a practical engineering default and record it as an assumption.

Construction Order

Choose the simplest supported construction whose parameters directly express the requested dimensions. Use a stable order:

1. establish the body and functional coordinate frame;
2. create primary additive volume(s);
3. create any selector-hosted feature before its named source output is changed by a fuse, cut, shell, pattern, or finishing operation;
4. add remaining bosses, ribs, and other major additive geometry;
5. make remaining pockets, bores, and through features;
6. apply patterns, then fillets and chamfers last.

Every feature must list each feature it actually uses in depends_on. Prefer one complete profile-driven feature for a planar silhouette. Use primitives when their axis, radius, and height directly express the part. For through cuts, choose the operation's through extent and make the tool cross the material; never rely on coincident faces or a guessed nearby face. Delay dress-up operations because they can alter downstream topology.

The selector-source rule is an intentional exception to a generic “all adds, then all cuts” sequence. For example, a bolt circle hosted on an original flange cap must be placed immediately after the base when later additive fusions replace that exact cap. A required final through-cut can still follow all additive features and the earlier bolt operation.

Use only the supplied operation list. Follow each operation's parameter schema exactly, including required sketch state. Do not invent unsupported operation parameters, implicit booleans, or a substitute operation after a capability error.

Sketches And Coordinates

Keep a sketch to exactly workplane and profile. The workplane declares its origin, x_dir, and normal. Profile coordinates are local to that workplane. For primitive axes, origin_mm is the start-cap center and direction is the positive build direction. For a selector-hosted hole, position coordinates are world coordinates unless the operation contract explicitly says otherwise.

The Authoring sketch syntax is deliberately smaller than Runtime CDSL. For every sketch operation, emit exactly this shape. profile is singular, circles use the requested diameter_mm, and the local center is center_mm:

{
  "workplane": {
    "origin_mm": [0, 0, 12],
    "x_dir": [1, 0, 0],
    "normal": [0, 0, 1]
  },
  "profile": {
    "type": "circle",
    "diameter_mm": 56,
    "center_mm": [0, 0]
  }
}

Do not write profiles, plane, support, radius_mm, center, or any other key inside an Authoring sketch. The compiler derives Runtime radius and sketch identity. Use a primitive such as cylinder_add when its axis, radius, and height directly express the requested geometry and no sketch is needed.

Name features for their manufacturing role, for example base_plate, front_hub_boss, center_bore, and bolt_holes. Names make dependencies and repair diagnostics readable; they are not server identities.

Selectors

The operation metadata states whether selectors are required, their kind, cardinality, and server-side destination. Put only declarative selectors in a feature's selectors array. Never write the destination field itself inside params.

For an output face, use an exact local role embedded in source and state a unique match:

{
  "kind": "face",
  "source": "front_hub_boss.top_planar_face",
  "match": "unique"
}

Do not add role, query, host_face, a face index, a coordinate selector, or a Runtime selector token. The source value is the complete local intent. The compiler adds its source feature as an auditable graph dependency; include other true construction dependencies in depends_on yourself.

top_planar_face and end_face mean the positive-direction cap of a supported extrude, sweep, loft, or cylinder. bottom_planar_face and start_face mean the opposite cap. Select the most recent feature whose output is known to be the required host; do not select a similar face by location, face index, or proximity.

Translate a request's descriptive max_z/min_z wording into these output roles before writing CDSL. Never emit base.max_z_face or base.min_z_face. For a cylinder built in +Z, the top cap is top_planar_face and the bottom cap is bottom_planar_face; reverse-direction features swap their world-Z position but retain their own start/end roles.

hole_wizard requires exactly one face selector. It uses that selector as its host face, so a central bore on a hub should select the hub cap, while a bolt circle on an exposed flange should select the flange cap. A selector must name a host that contains every requested hole position. If that cannot be made unique, redesign the feature sequence or omit the unsupported feature; never guess a face.

Before creating a hosted hole, calculate each position against the actual host face. A local boss can be the global highest face while being too small to host a larger bolt circle. In that case use the exposed flange cap at the bolt radius, with its own plane height, rather than the global maximum-Z cap. Place the hosted holes while that source cap's exact provenance is still active: before a later fusion or cut would split, remove, or replace it. A final through-cut may still follow all additive features, so a bolt circle can be hosted before an unrelated final boss and before that final cut.

Acceptance And Repair

Describe only user-requested, measurable acceptance targets in acceptance_targets; leave inferred dimensions in assumptions. On repair, return a complete replacement document. Preserve feature names and every feature listed in executed_feature_ids, except a feature explicitly named by the diagnostic. Features that were never executed may be changed freely to repair an invalid selector, parameter, dependency, or geometry construction.

Read structured diagnostics literally. Fix their named cause with the smallest document change, then return the entire document. Do not add internal IDs, weaken a requested value, silently delete a failed feature, or replace a failed selector with an arbitrary topology element.