---
name: cad-script-authoring
description: >
  Write the final build123d CAD generator script and verification tests using
  plan.md and available research artifacts. The orchestrator is the single
  writer. Use after research obligations are satisfied for the current plan.
---

# CAD Script Authoring

## Purpose

Produce a working, tested CAD generator script.

## Pre-Authoring Checklist

- [ ] `plans/<model_slug>/plan.md` exists and is approved.
- [ ] Read `plans/<model_slug>/plan.md`.
- [ ] If Stage 2 produced new research, read `research/<model_slug>/implementation-brief.md`.
- [ ] For modify workflows with no new research, inspect the existing `models/<model_slug>/` and `tests/<model_slug>/` artifacts before editing.
- [ ] If any API details are unclear from the brief, read the referenced source files using Serena before writing code:
  ```
  mcp({ tool: "find_symbol", server: "serena", args: '{"name_path_pattern": "<ClassName>", "include_body": true}' })
  ```
- [ ] If anything is still unclear after inspection, go back to research (re-invoke `build123d-research`) or ask the user.

## Authoring Procedure

1. Choose builder mode (`BuildPart`/`BuildSketch`/`BuildLine` context managers) as the default unless algebra mode is clearly simpler for the specific geometry.
2. Create or update `models/<model_slug>/<name>.py`:
   - Module docstring referencing `plans/<model_slug>/plan.md`.
   - All configurable dimensions as top-level constants or function parameters.
   - `from build123d import *` as the standard import.
   - Main generation logic.
   - Export call(s) at the bottom (e.g., `export_step(result, "output/<model_slug>/<name>.step")`).
   - `if __name__ == "__main__":` guard for standalone execution.
   - For modify workflows, edit the existing generator in place when possible instead of rewriting unrelated model scripts.
3. Create or update `tests/<model_slug>/test_<name>.py`:
   - Import the generator function/module.
   - Update or add only the tests needed for the changed behavior while preserving relevant existing verification for unchanged behavior.
   - Test: no exceptions during build.
   - Test: bounding box dimensions within expected ranges when the change affects deterministic geometry.
   - Test: key parameters produce expected changes when the modified behavior exposes them.
   - Test: export produces file on disk (if applicable).

## Verification-First Rules

- For deterministic behavior (parameter validation, dimensions, export): write tests alongside code.
- For exploratory geometry: spike in a `scratch/` file, then move to `models/` with tests once the approach works.
- Never commit to `models/` without at least the "no exceptions" test.
- For modify workflows, prefer targeted test updates for the requested change instead of rewriting unrelated suites.

## Post-Authoring

1. Run the affected tests first: `$PRIMUS_VENV_PYTHON -m pytest tests/<model_slug>/test_<name>.py -v`
2. Re-run any broader verification still needed for unchanged critical behavior.
3. Fix any failures.
4. Commit: `git add models/ tests/ && git commit -m "feat: add <name> generator + tests"`
5. Proceed to Stage 4 (review).

## build123d Style Rules

- Prefer explicit dimensions over magic numbers.
- Use `Mode.SUBTRACT` for holes/cutouts, not boolean workarounds.
- Use `fillet`/`chamfer` on selected edges, not entire parts.
- Use selectors (`edges().filter_by(Axis.Z)`, `faces().sort_by(Axis.Z)[-1]`) for precise feature targeting.
- Comment non-obvious geometry decisions.