- skillproj.toml: targets omp,opencode + zcode,claudecode,codex,dsh,kimicode - single-part-modeling: 5 host-binding pairs -> 10 (ask tool, TODO tool, REPL/script hypothesis loop, plan state machine, isolated image review) - zcode+claudecode share one block per binding (AskUserQuestion/TodoWrite/ Agent-Task); codex = plain-text batched questions + update_plan + user as fallback reviewer; dsh/kimicode = conservative fallback pending native tool mapping - references README generalizes the omp-only wording
57 KiB
Workflow: Single-Part Modeling
Model one physical part from confirmed requirements to validated, optionally packaged geometry. The workflow is role-structured. Roles 1 and 2 establish the requirements and the stage plan; Roles 3 and 4 then run a strict, stage-by-stage TDD loop; Role 5 exports only after every stage gate passes.
Standing discipline, binding for every role:
- Serial stages, no bundling. Do not prepare a later stage's model or
verification artifact early. Finish the current stage gate before entering
the next
Sstage. - Verifier before model. For every stage, define and exercise the verification contract before editing the real part source. A model is not accepted because it builds; it is accepted only when the prepared checks pass.
- ⛔ BLOCKING means stop. At a blocking gate, wait for the explicit user answer. Never decide on the user's behalf.
- Image judgments are delegated. Visual checks are planned by Role 3 before the stage model is built; the render may be produced by Role 4 afterward, but its acceptance verdict is supplied by an isolated subagent.
- Standard parts first. If the requirement can be satisfied by a
standard part, or by a part based on one (gear, ring gear, rack,
cycloidal disc, bearing, fastener),
scad.std.*MUST be the basis — hand-modeling a standard shape is a defect, not a fallback. A single std part with no assembly context stays in this workflow viadomains/standard-parts.md; a mechanism mating several std parts routes toassembly-product-build.md. - Sketch tier is the default part form. Per the Feature Tree
Convention, planar profiles and planar paths are sketch tier. When a
stage's profiles are sketch tier, its verification contract includes
the sketch gates: solve status and remaining DOF recorded before
promotion, and promotion preserving measured geometry (closure, area,
bounds compare). Plan entities and constraints with stable ids and
evidence-backed constraints; intentional free DOF are recorded in the
brief, never left silent. Capability detail:
domains/sketch-and-features.md. - Feature Tree Convention. Every part source is authored as
block-structured features per
discipline/feature-tree-convention.md(sketch → basic body op → bool → modifier, one feature per block with its boundary comment); read it before Role 4 writes any model source. - Repair the owning artifact. A failed verification reopens the current stage's verifier contract or model, whichever owns the failure. Never patch downstream symptoms or weaken a check to pass it.
Role map
| # | Role | Reads (load before acting) | Produces | Exit gate |
|---|---|---|---|---|
| 1 | Requirement Confirmer | domains/requirement-refinement.md, discipline/requirement-and-cad-brief.md |
<part-dir>/REQUIREMENTS.md |
⛔ user consent received |
| 2 | Master Planner | REQUIREMENTS.md, discipline/mechanical-modeling.md, discipline/datums-and-coordinate-systems.md |
<part-dir>/BUILD_PLAN.md + base TODOs |
plan presented |
| 3 | Verifier Planner | REQUIREMENTS.md, BUILD_PLAN.md, discipline/geometric-validation.md, exact API/diagnostic pages used by the check |
current-stage verification contract, hypothesis snippets, executable verification script, plan verifier and run verifier TODO items |
verification artifact is ready before modeling |
| 4 | Detail Modeling Planner & Builder | current stage's verifier contract, domains/part-modeling.md, discipline/feature-ordering.md, discipline/feature-tree-convention.md, exact modeling API pages |
current-stage model, operation hypotheses, rendered evidence inputs | model runs and the prepared verifier passes |
| 5 | Exporter | REQUIREMENTS.md export rows, domains/export-and-translation.md, domains/assembly-and-product.md |
.scadpkg + requested exports, readability check |
artifacts re-open cleanly |
Role-switch protocol
Before starting a role's work, output exactly:
## [Role Switch: <Role Name>]
Reading: <role-owned files>
Artifact out: <path>
Then act only inside that role's scope. Roles 3 and 4 switch for each Master-Planner stage as follows:
S1: Role 3 plan verifier -> Role 4 build -> Role 3 run/review verifier
S2: Role 3 plan verifier -> Role 4 build -> Role 3 run/review verifier
...
Sn: Role 3 plan verifier -> Role 4 build -> Role 3 run/review verifier
Role 3 may use hypotheses to design a check, but may not certify a model it
has not tested. Role 4 may use modeling hypotheses, but may not start a stage
until that stage's verification contract and script exist. A failed stage does
not advance the TODO; it appends or starts a repair: item for the owning
artifact and repeats the same Role 3/4 loop.
Role 1 — Requirement Confirmer ⛔
Convert the request into REQUIREMENTS.md. No geometry, no probe builds,
no source-file writes before this role's gate closes.
Procedure:
- Classify inputs (prose / reference images / drawings / mesh models ,etc.). For any image
containing reference structure: write the interpreted shape region by
region — overall form, visible features and locations, symmetry and
orientation, anything hidden or uncertain. Describing is not
confirming: the interpretation ends as part of ONE batched ask round
that also covers the Ask-or-Record blocking table
(
domains/requirement-refinement.md). Shape-level facts are always confirmed; only dimension-level defaults may be assumed once a scale anchor exists. For provided models(most cases are mesh), use python code to render and inspect geometry information through something like sampling / fitting, which may provide useful geometry information for you to build similar stucture / rebuild same struction in brep through simplecadapi. - For undetermined parameters / geometry / function / performance, propose recommended assumptions as ask options (default first) so the user can accept or override in one round.
Host binding: designing the Role 1 ask payload (omp)
OMP already provides and executes the ask tool. This block defines only how
to design its input for the Requirement Confirmer. After writing the
region-by-region interpretation and the Ask-or-Record ledger, make one batched
call for all unresolved items that can block REQUIREMENTS.md.
Design each question so its answer can be copied into one ledger row:
- Ask about one decision, not one vague topic. Name the affected region, feature, axis, or interface and state the evidence or ambiguity.
- Ask shape-level interpretation explicitly. Do not hide a disputed region in a general "does this look right?" question.
- Separate independent decisions such as overall orientation, hole axis,
thread representation, and mounting intent. Use
multi: trueonly when the user may independently select several items from the same set. - Make options mutually exclusive and operational: each option must say what will be recorded and what modeling consequence follows. Do not offer imaginary precision that the source does not support.
- Put the conservative, clearly labeled assumption first and set
recommended: 0; this is a recommendation, never consent. Include a concrete correction path in the options so the user can reject or amend the interpretation. - Ask only blocking decisions in this round. Record inferable dimensions and low-risk defaults as assumptions with their basis; do not burden the user with API or verification choices owned by later roles.
Example payload shape (the actual labels and questions must be derived from the current part, not copied literally):
ask({
questions: [
{
id: "region_c_flange_location",
question: "The drawing leaves the C-view flange location ambiguous. Which region is the C flange?",
options: [
{ label: "The -Y horizontal-port end", description: "Record C as the long rounded flange on the -Y end; model its axis along Y." },
{ label: "The top vertical-bore end", description: "Record C as the flange around the top vertical bore; revise the region map before modeling." }
],
recommended: 0
},
{
id: "thread_representation",
question: "The drawing calls out M36-6H, but does not establish whether thread faces are needed for this deliverable. How should it be represented?",
options: [
{ label: "Nominal bore", description: "Record the callout and model the nominal bore; do not create helical faces." },
{ label: "Explicit thread geometry", description: "Record modeled thread geometry as required and plan a thread-specific verification." }
],
recommended: 0
},
{
id: "mounting_intent",
question: "What mounting intent should the base holes represent?",
options: [
{ label: "Through-bolted to a flat base", description: "Record insertion along Z and verify the fastener envelope and underside clearance." },
{ label: "Tapped or blind mounting", description: "Record the hole termination and thread requirement; do not assume through holes." }
],
recommended: 0
}
]
})
Use stable machine-readable id values that match ledger rows. After the call,
copy the returned selected options, custom answers, notes, and any timeout
status into REQUIREMENTS.md; preserve the user's wording for corrections.
The gate closes only when every blocking row has an explicit answer or an
explicitly recorded assumption permitted by the requirement discipline. A
recommendation or timeout is not user consent. On cancellation, incomplete
answers, or unavailable interactive UI, keep the gate blocked and stop; never
continue by silently selecting the recommended option.
When a question has no valid answer among the proposed options, its wording must make clear what correction or missing requirement the user should supply. Do not ask the user to choose an implementation detail owned by a later role; ask only for the requirement that changes the model or its acceptance criteria.
Host binding: designing the Role 1 question payload (opencode)
opencode provides and executes the native question tool, which batches all
questions in one call. This block defines only how to design its input for
the Requirement Confirmer. After writing the region-by-region interpretation
and the Ask-or-Record ledger, make one batched call for all unresolved items
that can block REQUIREMENTS.md.
The tool schema differs from a generic ask; design around the differences:
- There is no
idfield. Key each ledger row to theheader(max 30 characters): derive it from the stable identifier you would otherwise use as an id, e.g.C-flange location,thread representation. - There is no
recommendedindex. Express the recommendation by putting the conservative, clearly labeled option first and suffixing its label with(Recommended); this is a recommendation, never consent. - A free-text "type your own answer" choice is offered automatically; do not
add your own catch-all option. Answers return as the selected option
labels (arrays when
multiple: true). Usemultiple: trueonly when the user may independently select several items from the same set. - Keep each
labelto a few words and put the operational consequence — what will be recorded and what modeling follows — indescription.
The shared design rules still apply: one decision per question, shape-level interpretation asked explicitly, independent decisions separated into their own questions, mutually exclusive and operational options, a concrete correction path in the options, and only blocking decisions in this round.
Example payload shape (the actual labels and questions must be derived from the current part, not copied literally):
question({
questions: [
{
header: "C-flange location",
question: "The drawing leaves the C-view flange location ambiguous. Which region is the C flange?",
options: [
{ label: "-Y horizontal-port end (Recommended)", description: "Record C as the long rounded flange on the -Y end; model its axis along Y." },
{ label: "Top vertical-bore end", description: "Record C as the flange around the top vertical bore; revise the region map before modeling." }
]
},
{
header: "Thread representation",
question: "The drawing calls out M36-6H but does not establish whether thread faces are needed for this deliverable. How should it be represented?",
options: [
{ label: "Nominal bore (Recommended)", description: "Record the callout and model the nominal bore; do not create helical faces." },
{ label: "Explicit thread geometry", description: "Record modeled thread geometry as required and plan a thread-specific verification." }
]
}
]
})
After the call, copy the selected labels, any typed custom answers, and the
questions' headers into REQUIREMENTS.md keyed by header; preserve the
user's wording for corrections. A dismissed or skipped question is an
unanswered blocking row: keep the gate blocked and stop; never continue by
silently selecting the recommended option. The gate closes only when every
blocking row has an explicit answer or an explicitly recorded assumption
permitted by the requirement discipline.
When a question has no valid answer among the proposed options, its wording must make clear what correction or missing requirement the user should type as the free-text answer. Do not ask the user to choose an implementation detail owned by a later role; ask only for the requirement that changes the model or its acceptance criteria.
Host binding: designing the Role 1 AskUserQuestion payload (Claude Code / ZCode)
The host provides and executes the AskUserQuestion tool. This block defines
only how to design its input for the Requirement Confirmer. After writing the
region-by-region interpretation and the Ask-or-Record ledger, make one batched
call for all unresolved items that can block REQUIREMENTS.md.
The schema differs from a generic ask; design around the differences:
- At most 4 questions per call. If more blocking rows remain, send the remaining rows as further batched calls in the same turn and say why.
header(max 12 characters, shown as a chip) is the ledger key: derive it from the stable identifier you would otherwise use as an id, e.g.C flange,thread.- There is no
recommendedindex. Put the conservative, clearly labeled option first and suffix its label with(Recommended); this is a recommendation, never consent. - 2–4 options per question; each option is a short
labelplus an operationaldescriptionsaying what will be recorded and what modeling follows. A free-text "Other" choice is offered automatically; do not add your own catch-all option. Answers return as the selected labels plus any typed notes. multiSelect: trueonly when the user may independently select several items from the same set.
The shared design rules still apply: one decision per question, shape-level interpretation asked explicitly, independent decisions separated into their own questions, mutually exclusive and operational options, a concrete correction path in the options, and only blocking decisions in this round. Example payload shape (the actual labels and questions must be derived from the current part, not copied literally):
AskUserQuestion({
questions: [
{
question: "The drawing leaves the C-view flange location ambiguous. Which region is the C flange?",
header: "C flange",
multiSelect: false,
options: [
{ label: "-Y port end (Recommended)", description: "Record C as the long rounded flange on the -Y end; model its axis along Y." },
{ label: "Top bore end", description: "Record C as the flange around the top vertical bore; revise the region map before modeling." }
]
}
]
})
After the call, copy the selected labels, any typed custom answers, and notes
into REQUIREMENTS.md keyed by header; preserve the user's wording for
corrections. A skipped question or an empty answer is an unanswered blocking
row: keep the gate blocked and stop; never continue by silently selecting the
recommended option. The gate closes only when every blocking row has an
explicit answer or an explicitly recorded assumption permitted by the
requirement discipline.
Host binding: Role 1 blocking questions without a native ask tool (codex)
codex provides no structured interactive-question tool. Keep the ledger
discipline in plain conversation: after writing the region-by-region
interpretation and the Ask-or-Record ledger, send ONE message listing every
unresolved item that can block REQUIREMENTS.md — one numbered question per
decision, lettered mutually exclusive options each stating the operational
consequence, the conservative interpretation first and marked
(recommended), and an explicit invitation to correct or type a different
answer. Then stop: make no further tool call until the user replies. Record
the reply verbatim in REQUIREMENTS.md under the same ledger keys, preserving
the user's wording for corrections. A partial answer or a general "sounds
good" does not answer the open rows: re-ask exactly those rows and keep the
gate blocked; never continue by silently selecting the recommended option.
The gate closes only when every blocking row has an explicit answer or an
explicitly recorded assumption permitted by the requirement discipline.
Host binding: Role 1 blocking questions, conservative fallback (dsh / kimicode)
No native interactive-question tool is assumed for this host, so use the
plain-text ledger discipline: after writing the region-by-region
interpretation and the Ask-or-Record ledger, send ONE message listing every
unresolved item that can block REQUIREMENTS.md — one numbered question per
decision, lettered mutually exclusive options each stating the operational
consequence, the conservative interpretation first and marked
(recommended), and an explicit invitation to correct or type a different
answer. Then stop and wait for the user's reply; record it verbatim in
REQUIREMENTS.md under the same ledger keys. A partial answer does not
answer the open rows: re-ask them and keep the gate blocked; never continue
by silently selecting the recommended option. If this host does provide a
native ask/question tool, map this block onto it and keep the same gate
semantics: one batched round, blocking decisions only, and a recommendation
that is never consent.
- Fastened or load-bearing parts: the requirements contain the envelope arithmetic, not just values — head diameter + shaft + wall/clearance → minimum land diameter, boss thickness, edge distance, and lateral offset along the insertion path.
- Write
REQUIREMENTS.md:
# Requirements: <part name>
- Inputs: <prose | images used | drawings>
- Functional goals: <what the part must do>
- Geometry targets: <confirmed shape description, region by region>
- Units / coordinate convention: <mm; origin, base plane, up axis>
- Named parameters (Var): <name = value | ASSUMED default>
- Fastening & mounting: <fastener, axis, head side, insertion path>
Envelope math: <head+shaft+wall -> min land / boss / offset>
- Service conditions: <load direction and class | none stated>
- Export targets: .scadpkg always; STEP/STL/OBJ/MJCF/FCStd if requested
- Verification intent: <what the user's words require proving>
- Ask-or-Record ledger: | item | asked/assumed | answer/value |
Gate: the ask round returned answers, consent is recorded in the ledger, and
REQUIREMENTS.md exists. Entering Role 2 without this gate is the cardinal
violation.
Role 2 — Master Planner
From REQUIREMENTS.md only — no API detail, no step-level modeling.
- Choose the construction strategy (profile-driven vs block-and-feature) and fix the datum from the functional interface; one-paragraph rationale each.
- Design the construction as numbered stages
S1..Sn. For each stage state exactly what new substructure is complete at its output boundary and what later stages are not yet included. Pair every stage with its future verification target, but leave the executable verification design to Role 3. - Write
BUILD_PLAN.mdwith the stage output boundaries, datum, intended construction strategy, and the requirement-to-stage mapping. Role 3 adds verification contracts and Role 4 adds modeling hypotheses and source details while the loop runs. - Initialize the TODO tool with phases
Requirements / Plan / Build & Verify / Export. For each stage create stableplan verifier,model, andrun verifieritems. Therun verifieritem is completed only after Role 3 has executed the prepared check against the Role 4 result. Mark Requirements done, Plan done, and start the first stage'splan verifieritem.
Present the plan in ≤10 lines. No approval gate; enter the Role 3/4 loop.
Host binding: TODO tool (omp)
Tool name: todo. Operations: init(list=[{phase, items[]}]),
start(task), done(task|phase), drop(task|phase), block(task, reason),
unblock(task), append(phase, items[]), rm, view. Contract: batch
todo calls together with real work in the same turn; task strings are stable
identifiers — quote them exactly when completing. Keep the current stage's
model item pending until its plan verifier artifact exists. A failed
run verifier reopens the owning verifier or model through a repair: item;
never advance the stage while either owner is open.
Host binding: TODO tool (opencode)
Tool name: todowrite. There is a single operation: submit the whole list
as todos=[{content, status, priority}] with statuses
pending / in_progress / completed / cancelled. Every call rewrites the
full list, so start, done, drop, and append are all expressed by including
every current item with its updated status in the next call. Contract: batch
the rewrite with real work in the same turn; content strings are the
stable identifiers — quote them exactly when completing (S1 plan verifier, repair: S1 verifier collision check); keep exactly one item
in_progress at a time; mark an item completed only at its actual gate,
never speculatively. There is no blocked status: a blocked item stays
in_progress and a follow-up item records the blocker. Keep the current
stage's model item pending until its plan verifier artifact exists. A
failed run verifier reopens the owning verifier or model through a
repair: item; never advance the stage while either owner is open.
Host binding: TODO tool (Claude Code / ZCode)
Tool name: TodoWrite. There is a single operation: submit the whole list as
todos=[{content, status, priority}] with statuses
pending / in_progress / completed and priorities high / medium / low.
Every call replaces the full list, so start, done, drop, and append are all
expressed by including every current item with its updated status in the next
call. Contract: batch the rewrite with real work in the same turn; content
strings are the stable identifiers — quote them exactly when completing
(S1 plan verifier, repair: S1 verifier collision check); keep exactly one
item in_progress at a time; mark an item completed only at its actual
gate, never speculatively. There is no blocked status: a blocked item stays
pending or in_progress and a follow-up repair: item records the
blocker. Keep the current stage's model item pending until its
plan verifier artifact exists. A failed run verifier reopens the owning
verifier or model through a repair: item; never advance the stage while
either owner is open.
Host binding: TODO tool (codex)
Tool name: update_plan. One operation: submit the whole plan as
plan=[{step, status}] with statuses pending / in_progress / completed.
Every call rewrites the full plan, so start, done, drop, and append are all
expressed by including every current step with its updated status in the next
call. Contract: batch the rewrite with real work in the same turn; step
strings are the stable identifiers — quote them exactly (S1 plan verifier,
repair: S1 verifier collision check); keep exactly one step in_progress
at a time; mark a step completed only at its actual gate, never
speculatively. There is no blocked status: a blocked step stays pending
or in_progress and a follow-up repair: step records the blocker. Keep the
current stage's model step pending until its plan verifier artifact
exists. A failed run verifier reopens the owning verifier or model through
a repair: step; never advance the stage while either owner is open. If
update_plan is unavailable in the current session, keep the same list as a
checklist section in BUILD_PLAN.md, update it in the same turn as the work
it gates, and quote the current checklist state when reporting a gate
decision.
Host binding: TODO tool, conservative fallback (dsh / kimicode)
No native TODO tool is assumed for this host. Keep the stage checklist as a
fenced checklist section in BUILD_PLAN.md and treat the file as the gate
ledger: update it in the same turn as the work it gates; quote the exact item
strings (S1 plan verifier, repair: S1 verifier collision check); keep
exactly one item marked in-progress; mark an item done only at its actual
gate, never speculatively; record blockers as repair: items instead of a
blocked status. Keep the current stage's model item pending until its
plan verifier artifact exists. A failed run verifier reopens the owning
verifier or model through a repair: item; never advance the stage while
either owner is open. When claiming a gate decision, quote the current
checklist state. If this host does provide a native TODO tool, map this block
onto it and keep the same gate semantics.
Role 3 — Verifier Planner
Role 3 runs before every stage's modeling work and owns the stage's verification contract. It is the modeling equivalent of writing tests before implementation.
For the current S stage, in order:
- Identify the stage output: name the substructure that must be complete, its datum/coordinate relationship, and the existing geometry it may touch. State what is deliberately out of scope until later stages.
- Translate the requirements into acceptance criteria for that output: dimensions and tolerances; required faces, holes, axes, or features; interfaces and fit with already-built geometry; collision and clearance; fastener insertion and tool access; assembly reachability; demolding or manufacturing access when relevant; absence of unintended interference; BREP validity and single-solid expectations. Include visual criteria when
- Turn every criterion into a deterministic check. Iterate through small hypothesis code snippets or probes in the available execution environment: deliberately good and bad probes must show that the proposed measurement, collision test, topology query, or visual review contract distinguishes pass from fail. Reject a check that merely prints a plausible value without testing the requirement.
- Produce the executable verification script or function for this stage,
including explicit pass/fail assertions, named measurements, and small
evidence prints. Append to
BUILD_PLAN.md:Verifier contract: <output> / Criteria: <...> / Script: <path or symbol>plus the hypothesis results and known-bad proof. - Update TODO before modeling: complete the current
plan verifieritem after the contract, executable check, hypothesis evidence, and known-bad proof are recorded. Themodelitem may then start. After Role 4 produces the stage result, startrun verifierand execute the exact prepared function or script against that result; only its passing output closes the stage.
Role 3 may prepare visual verification here. It defines named render views, close-ups, comparison regions, and the structured verdict required from an isolated reviewer. It does not treat a render it produced as its own visual acceptance.
Host binding: persistent REPL and TODO state machine for Verifier Planner (omp)
Use the persistent eval tool (language py) for hypothesis snippets and
known-bad probes. Keep setup, hypothesis, and final check cells incremental;
do not hide an unproven check in a temporary one-shot script. Use todo to
make the current stage's verification contract a real gate, not a note.
Role 2 creates the stable stage tasks in the Build & Verify phase. For each
stage, the initial task order is:
S1 plan verifier
S1 model
S1 run verifier
S2 plan verifier
S2 model
S2 run verifier
...
Use the exact task strings consistently. When Role 3 enters a stage, start its
plan verifier task:
todo(op="start", task="S1 plan verifier")
If a stage was added after the original initialization, append all three tasks as one ordered batch before starting the first one:
todo(op="append", phase="Build & Verify", items=[
"S3 plan verifier",
"S3 model",
"S3 run verifier",
])
todo(op="start", task="S3 plan verifier")
Do not append a later stage's tasks while the current stage is still open. A repair item for the current stage is the exception: append it next to the owning task and keep the stage open.
After the verifier contract, executable check, hypothesis evidence, and
known-bad proof are recorded in BUILD_PLAN.md, close the planning gate and
open the modeling gate in the same work turn:
todo(op="done", task="S1 plan verifier")
todo(op="start", task="S1 model")
Role 4 owns the model task. It must not start before the plan verifier task
is done. After Role 4's source run completes, Role 4 closes S1 model and
starts S1 run verifier; Role 3 then executes the exact prepared function or
script named in that task.
On a passing verification, record the output/evidence and close the gate:
todo(op="done", task="S1 run verifier")
Only then may Role 3 start S2 plan verifier. On a failed check, do not call
done, drop, or rewrite the acceptance criterion merely to clear the list.
Identify the owner and append a stable repair task in the same phase, for
example:
todo(op="append", phase="Build & Verify", items=[
"repair: S1 verifier collision check",
])
todo(op="start", task="repair: S1 verifier collision check")
If the check is wrong, repair and re-prove the verifier contract; if the model
is wrong, keep the verifier task intact and append a model repair item. After
repair, return to the current stage's run verifier; never advance to S2.
Use todo(op="view") after a repair or interruption to re-ground task text
and status. Batch TODO calls with the real REPL, file, or verification work in
the same turn; keep task strings stable and mark each item done immediately at
its actual gate.
Host binding: file-based hypothesis loop and TODO state machine for Verifier Planner (opencode)
opencode has no persistent REPL. Python runs through the bash tool and
every invocation is a fresh process: names do not survive between calls.
Keep each hypothesis snippet, known-bad probe, and final check as a numbered
script file under the part directory (e.g.
<part-dir>/verify/s1_hypothesis.py, s1_known_bad.py, s1_verify.py)
and run it with python via bash; persist intermediate state in files
(JSON, pickle, or a captured package) and reload it in the next script. The
script file is the evidence: do not hide an unproven check in a throwaway
one-shot command whose text is lost. Use todowrite to make the current
stage's verification contract a real gate, not a note.
Role 2 creates the stable stage tasks in the Build & Verify phase. For
each stage, the initial task order is:
S1 plan verifier
S1 model
S1 run verifier
S2 plan verifier
S2 model
S2 run verifier
...
Use the exact task strings as content values in every todowrite call.
When Role 3 enters a stage, submit the full list with that item as the only
in_progress entry. If a stage is added after the original initialization,
add its three tasks as one ordered batch in the next rewrite before starting
the first one; do not add a later stage's tasks while the current stage is
still open. A repair item for the current stage is the exception: add it
next to the owning task and keep the stage open.
After the verifier contract, executable check, hypothesis evidence, and
known-bad proof are recorded in BUILD_PLAN.md, close the planning gate and
open the modeling gate in one rewrite: S1 plan verifier -> completed,
S1 model -> in_progress. Role 4 owns the model task; it must not be
in_progress while S1 plan verifier is unfinished. After Role 4's source
run completes, mark S1 model completed, set S1 run verifier
in_progress, and execute the exact prepared script named in that task.
On a passing verification, record the output/evidence and mark S1 run verifier completed; only then may S2 plan verifier become in_progress.
On a failed check, do not flip statuses merely to clear the list: identify
the owner, add a stable repair: item (e.g. repair: S1 verifier collision check), make it the in_progress item, and after the repair return to the
current stage's run verifier; never advance to S2. The todowrite
result echoes the current list — use it to re-ground task strings and status
after a repair or an interruption. Batch each rewrite with the real bash,
file, or verification work in the same turn.
Host binding: file-based hypothesis loop and TODO state machine for Verifier Planner (Claude Code / ZCode)
This host has no persistent REPL. Python runs through the Bash tool and
every invocation is a fresh process: names do not survive between calls.
Keep each hypothesis snippet, known-bad probe, and final check as a numbered
script file under the part directory (e.g.
<part-dir>/verify/s1_hypothesis.py, s1_known_bad.py, s1_verify.py) and
run it with python via Bash; persist intermediate state in files (JSON,
pickle, or a captured package) and reload it in the next script. The script
file is the evidence: do not hide an unproven check in a throwaway one-shot
command whose text is lost. Use TodoWrite to make the current stage's
verification contract a real gate, not a note.
Role 2 creates the stable stage tasks in the Build & Verify phase. For each
stage, the initial task order is:
S1 plan verifier
S1 model
S1 run verifier
S2 plan verifier
S2 model
S2 run verifier
...
Use the exact task strings as content values in every TodoWrite call.
When Role 3 enters a stage, submit the full list with that item as the only
in_progress entry. If a stage is added after the original initialization,
add its three tasks as one ordered batch in the next rewrite before starting
the first one; do not add a later stage's tasks while the current stage is
still open. A repair: item for the current stage is the exception: add it
next to the owning task and keep the stage open.
After the verifier contract, executable check, hypothesis evidence, and
known-bad proof are recorded in BUILD_PLAN.md, close the planning gate and
open the modeling gate in one rewrite: S1 plan verifier -> completed,
S1 model -> in_progress. Role 4 owns the model task; it must not be
in_progress while S1 plan verifier is unfinished. After Role 4's source
run completes, mark S1 model completed, set S1 run verifier
in_progress, and execute the exact prepared script named in that task.
On a passing verification, record the output/evidence and mark S1 run verifier completed; only then may S2 plan verifier become in_progress.
On a failed check, do not flip statuses merely to clear the list: identify
the owner, add a stable repair: item (e.g. repair: S1 verifier collision check), make it the in_progress item, and after the repair return to the
current stage's run verifier; never advance to S2. The TodoWrite result
echoes the current list — use it to re-ground task strings and status after a
repair or an interruption. Batch each rewrite with the real Bash, file, or
verification work in the same turn.
Host binding: file-based hypothesis loop and plan state machine for Verifier Planner (codex)
codex has no persistent REPL. Python runs through the shell tool and every
invocation is a fresh process: names do not survive between calls. Keep each
hypothesis snippet, known-bad probe, and final check as a numbered script
file under the part directory (e.g. <part-dir>/verify/s1_hypothesis.py,
s1_known_bad.py, s1_verify.py), run it with python through the shell,
and persist intermediate state in files (JSON, pickle, or a captured package)
reloaded by the next script. The script file is the evidence: do not hide an
unproven check in a throwaway one-shot command whose text is lost. Use
update_plan to make the current stage's verification contract a real gate,
not a note.
Role 2 creates the stable stage steps in the Build & Verify phase in the
order S1 plan verifier, S1 model, S1 run verifier, then S2 ..., and
so on. Use the exact step strings in every update_plan call. When Role 3
enters a stage, submit the full plan with that step as the only in_progress
entry. If a stage is added after the original initialization, add its three
steps as one ordered batch in the next rewrite before starting the first one;
do not add a later stage's steps while the current stage is still open. A
repair: step for the current stage is the exception: add it next to the
owning step and keep the stage open.
After the verifier contract, executable check, hypothesis evidence, and
known-bad proof are recorded in BUILD_PLAN.md, close the planning gate and
open the modeling gate in one rewrite: S1 plan verifier -> completed,
S1 model -> in_progress. Role 4 owns the model step; it must not be
in_progress while S1 plan verifier is unfinished. After Role 4's source
run completes, mark S1 model completed, set S1 run verifier
in_progress, and execute the exact prepared script named in that step.
On a passing verification, record the output/evidence and mark S1 run verifier completed; only then may S2 plan verifier become in_progress.
On a failed check, do not flip statuses merely to clear the list: identify
the owner, add a stable repair: step, make it the in_progress step, and
after the repair return to the current stage's run verifier; never advance
to S2. Batch each rewrite with the real shell, file, or verification work
in the same turn.
Host binding: file-based hypothesis loop and checklist state machine for Verifier Planner (dsh / kimicode)
No persistent REPL or native TODO tool is assumed for this host. Python runs
through the shell and every invocation is a fresh process: names do not
survive between calls. Keep each hypothesis snippet, known-bad probe, and
final check as a numbered script file under the part directory (e.g.
<part-dir>/verify/s1_hypothesis.py, s1_known_bad.py, s1_verify.py),
run it with python through the shell, and persist intermediate state in
files (JSON, pickle, or a captured package) reloaded by the next script. The
script file is the evidence: do not hide an unproven check in a throwaway
one-shot command whose text is lost.
Keep the stage checklist (S1 plan verifier, S1 model, S1 run verifier,
then S2 ...) as a fenced checklist section in BUILD_PLAN.md and treat it
as the gate ledger: when Role 3 enters a stage, mark that stage's
plan verifier item in-progress in the same turn; when the verifier
contract, executable check, hypothesis evidence, and known-bad proof are
recorded, mark S1 plan verifier done and S1 model in-progress in one
edit. Role 4 owns the model item and must not start while S1 plan verifier
is unfinished. After Role 4's source run completes, mark S1 model done, set
S1 run verifier in-progress, and execute the exact prepared script named in
that item. On a passing verification, record the output/evidence and mark
S1 run verifier done; only then may S2 plan verifier start. On a failed
check, do not edit statuses merely to clear the list: identify the owner, add
a stable repair: item next to the owning item, and after the repair return
to the current stage's run verifier; never advance to S2. Quote the
current checklist state when reporting a gate decision. Batch each checklist
edit with the real shell, file, or verification work in the same turn.
Role 4 — Detail Modeling Planner & Builder
Role 4 starts only after Role 3's current-stage verifier contract and executable check exist. It owns the detailed construction of the current stage, not the acceptance definition.
For the current stage:
-
Read the verifier contract, then choose a construction strategy from the geometry and the controlling dimensions. The categories below are a design ladder, not an API whitelist: select the operations that express the current stage's design intent, then read the exact documentation page for every operation before its first call. A method absent from its page does not exist.
- Profile and sketch first when they control the shape. Analyze the
required 2D sections, symmetry, datum planes, and dimensional relations.
Use
make_sketch_rsketchwith the applicableconstrain_*APIs andinspect_sketch_rsketchresultwhen a constrained sketch carries design intent; promote it throughmake_wire_from_sketch_rwireormake_face_from_sketch_rface. Build solids from that intent withextrude_rsolid,revolve_rsolid,loft_rsolid,sweep_rsolid, or a helical sweep when the feature is genuinely helical. A closed profile is preferred when its parameters directly represent the requirement. - Primitives are an alternative for genuinely regular base forms. Use a box, cylinder, cone, sphere, or other documented primitive when it maps directly to the controlled form; do not force a sketch only because one exists. Keep the controlling dimensions as named parameters either way.
- Build named feature solids, then combine them deliberately. Start
from a named base solid, create each additive boss/rib/flange or
subtractive bore/pocket/opening as a separately named solid or tool, then
use
union_rsolid,cut_rsolid, orintersect_rsolidto obtain the next single Solid. Repeat construct-feature -> Boolean -> verify for each required feature group; ensure intentional positive overlap for unions and tool overshoot for cuts. Do not assemble an opaque final shape in one expression. - Use advanced features only after the prototype feature is proven.
Validate one representative feature before
linear_pattern_rsolidlistorradial_pattern_rsolidlist; use documented transforms or mirrors for symmetry. Applyfillet_rsolid,chamfer_rsolid,shell_rsolid, and similar topology-sensitive features after their supporting geometry and selectors are stable. - Use surface construction when the requirement is surface-led. Consider documented ruled, patch, Bezier, Gordon, cylindrical, trimmed, sewn, or lofted surfaces; turn a closed, valid shell into a Solid only when that is the required topology. Do not approximate a freeform or transition surface with arbitrary primitives merely because booleans are familiar.
- Profile and sketch first when they control the shape. Analyze the
required 2D sections, symmetry, datum planes, and dimensional relations.
Use
-
Name every meaningful construction step before it is used: source variables, helper functions, exposed parameters, and tags must identify the part role or feature rather than its creation order. Prefer names such as
mounting_base,port_bore_tool,front_flange, andfeature.mounting_boreovershape2,cut1, or numeric topology indexes. Attach semantic tags withapply_tag(shape=..., tag=...), inspect them withlist_tags(shape=...), and use tag-aware QL selection where later features or verification need stable intent. Userole.*,feature.*, andtool.*namespaces; keep numeric facts in metadata rather than tags. -
Use small hypothesis code snippets or probes in the available execution environment to test the proposed construction sequence on minimal solids. Print types, counts, volumes, bounds, tag/selection cards, and other facts required by the verifier contract. Adopt an operation only when its evidence shows that it can produce the required shape. Append
Hypothesis: ... / Result: ... / Adopted: ...under the current stage inBUILD_PLAN.md. -
Edit the part source only after the operation hypotheses pass. Use keyword arguments, named parameters, role/feature/tool tags, and QL fact prints; include selection cards before every fillet/chamfer.
-
Run the source and hand the resulting stage geometry to Role 3. Role 3 executes the exact prepared verification script. The stage passes only when all assertions, measurements, fit/access checks, and required visual verdicts pass. A visual verdict comes from the isolated reviewer contract planned by Role 3.
-
On failure, do not weaken the check. Determine whether the verifier contract or the model owns the defect, add a
repair:TODO to that owner, and repeat Role 3/4 for the same stage. Start the next stage only after the current stage'smodelandrun verifieritems are both complete.
Host binding: persistent REPL for Detail Modeling Planner & Builder (omp)
Use eval (language py) for incremental construction hypotheses; names
survive across calls. Keep the real source run in bash. Never use a modeling
success message as the verification result: invoke the prepared verifier
function or script and record its output in the stage evidence.
Host binding: file-based hypothesis loop for Detail Modeling Planner & Builder (opencode)
opencode has no persistent REPL; run incremental construction hypotheses as
numbered scripts under the part directory (e.g.
<part-dir>/hypotheses/s1_base_probe.py) through bash. Names do not
survive between runs: carry intermediate geometry between probes by writing
it to a file (pickle, JSON, or capture) and reloading, or by
re-materializing from the part source. Keep the real source run in bash
too. Never use a modeling success message as the verification result:
invoke the prepared verifier script and record its output in the stage
evidence.
Host binding: file-based hypothesis loop for Detail Modeling Planner & Builder (Claude Code / ZCode)
This host has no persistent REPL; run incremental construction hypotheses as
numbered scripts under the part directory (e.g.
<part-dir>/hypotheses/s1_base_probe.py) through the Bash tool. Names do
not survive between runs: carry intermediate geometry between probes by
writing it to a file (pickle, JSON, or a captured package) and reloading, or
by re-materializing from the part source. Keep the real source run in Bash
too. Never use a modeling success message as the verification result: invoke
the prepared verifier script and record its output in the stage evidence.
Host binding: file-based hypothesis loop for Detail Modeling Planner & Builder (codex)
codex has no persistent REPL; run incremental construction hypotheses as
numbered scripts under the part directory (e.g.
<part-dir>/hypotheses/s1_base_probe.py) through the shell tool. Names do
not survive between runs: carry intermediate geometry between probes by
writing it to a file (pickle, JSON, or a captured package) and reloading, or
by re-materializing from the part source. Keep the real source run in the
shell too. Never use a modeling success message as the verification result:
invoke the prepared verifier script and record its output in the stage
evidence.
Host binding: file-based hypothesis loop for Detail Modeling Planner & Builder (dsh / kimicode)
No persistent REPL is assumed for this host; run incremental construction
hypotheses as numbered scripts under the part directory (e.g.
<part-dir>/hypotheses/s1_base_probe.py) through the shell. Names do not
survive between runs: carry intermediate geometry between probes by writing
it to a file (pickle, JSON, or a captured package) and reloading, or by
re-materializing from the part source. Keep the real source run in the shell
too. Never use a modeling success message as the verification result: invoke
the prepared verifier script and record its output in the stage evidence.
Verifier contract patterns
Role 3 selects the applicable checks per stage; it does not mechanically run every pattern. A contract may combine:
- dimensional measurements with explicit tolerance bounds;
- topology, axis, and face-location queries for required features;
- BREP closure, positive volume, and solid-count checks;
- swept insertion envelopes for screws, tools, or assembly access, with a zero-collision criterion;
- clearance and interference checks against already-built substructures;
- demolding or tool-direction access checks when manufacturing intent requires;
- named renders and isolated per-region visual verdicts;
- functional motion or clearance checks when the part has moving interfaces;
- FEM only when service conditions are stated in
REQUIREMENTS.md.
Every selected pattern needs a deterministic pass/fail condition and a known-bad hypothesis proof before the current stage is modeled.
Host binding: mandatory isolated image review (omp)
When Role 3 selects visual verification, any image-based acceptance judgment must be executed by a clean-context reviewer. The context that produced a render cannot certify it. Role 3 defines the visual contract before Role 4 builds: reference/render paths, named views, regions, required verdict fields, and the reviewer input description.
- Default: spawn one isolated
taskreviewer with file paths and the written shape description fromREQUIREMENTS.md; demand structured per-regionmatch/mismatch/unreviewableverdicts with reasons. - If a standing reviewer peer exists, use
hubto send the same contract and record its reply verbatim. - A mismatch cannot be overridden by the main context. Repair the owning model, render again, and repeat the isolated review.
- If neither reviewer mechanism exists, the visual gate remains open and the stage cannot pass.
Host binding: mandatory isolated image review (opencode)
When Role 3 selects visual verification, any image-based acceptance judgment must be executed by a subagent with a clean context. The context that produced a render cannot certify it. Role 3 defines the visual contract before Role 4 builds: reference/render paths, named views, regions, required verdict fields, and the reviewer input description.
- Default and only mechanism: spawn one isolated reviewer with the
tasktool,subagent_type: "general"(fresh context, able to read image files). Pass the render/reference file paths and the written shape description fromREQUIREMENTS.md; require structured per-regionmatch/mismatch/unreviewableverdicts with reasons in the reviewer's final report, and quote that report verbatim in the stage evidence. Spawn a fresh reviewer for every re-review; do not resume a previous reviewer session (task-id reuse would carry the context of the earlier render it already judged). - opencode has no standing-reviewer-peer mechanism; the hub option cannot
be mapped. If the
tasktool is unavailable, the visual gate remains open and the stage cannot pass. - A mismatch cannot be overridden by the main context. Repair the owning model, render again, and repeat the isolated review.
Host binding: mandatory isolated image review (Claude Code / ZCode)
When Role 3 selects visual verification, any image-based acceptance judgment must be executed by a subagent with a clean context. The context that produced a render cannot certify it. Role 3 defines the visual contract before Role 4 builds: reference/render paths, named views, regions, required verdict fields, and the reviewer input description.
- Default and only mechanism: spawn one isolated reviewer subagent (ZCode
Agenttool / Claude CodeTasktool,subagent_type: "general-purpose"— fresh context, able to read image files). Pass the render/reference file paths and the written shape description fromREQUIREMENTS.md; require structured per-regionmatch/mismatch/unreviewableverdicts with reasons in the reviewer's final report, and quote that report verbatim in the stage evidence. The subagent's final message is the review record. - Spawn a fresh reviewer for every re-review; do not resume a previous reviewer session or reuse a task id (its context carries the earlier render it already judged, so it can no longer certify a new one).
- This host has no standing-reviewer-peer mechanism; the hub option cannot be mapped. If the subagent spawn tool is unavailable, the visual gate remains open and the stage cannot pass.
- A mismatch cannot be overridden by the main context. Repair the owning model, render again, and repeat the isolated review.
Host binding: mandatory isolated image review (codex)
When Role 3 selects visual verification, any image-based acceptance judgment must come from a context that did not produce the render; the modeling context cannot certify it. Role 3 defines the visual contract before Role 4 builds: reference/render paths, named views, regions, required verdict fields, and the reviewer input description.
- codex has no subagent spawn mechanism. The fallback reviewer is the user:
present the render together with the written visual contract (views,
regions, and the verdict fields you need) in one message, then stop and
wait. Record the user's verdict verbatim in the stage evidence as the
review record; a partial verdict is
unreviewablefor the uncovered regions. - If the user cannot review in this round, the visual gate remains open and the stage cannot pass; do not substitute the modeling context's own judgment for the review.
- A mismatch cannot be overridden by the modeling context. Repair the owning model, render again, and repeat the review.
Host binding: mandatory isolated image review, conservative fallback (dsh / kimicode)
When Role 3 selects visual verification, any image-based acceptance judgment must come from a context that did not produce the render; the modeling context cannot certify it. Role 3 defines the visual contract before Role 4 builds: reference/render paths, named views, regions, required verdict fields, and the reviewer input description.
- No subagent mechanism is assumed for this host. If the host provides one,
spawn an isolated reviewer subagent with fresh context per re-review, pass
the render/reference paths and the written shape description, require
structured per-region
match/mismatch/unreviewableverdicts with reasons, and quote its report verbatim in the stage evidence. - Without a subagent mechanism, the fallback reviewer is the user: present the render together with the written visual contract in one message, then stop and wait; record the user's verdict verbatim as the review record. If the user cannot review in this round, the visual gate remains open and the stage cannot pass.
- A mismatch cannot be overridden by the modeling context. Repair the owning model, render again, and repeat the review.
Role 5 — Exporter
Read the export rows from REQUIREMENTS.md. Durable canonical delivery is
capture(result, "out/<part>.scadpkg"); external formats go through
domains/export-and-translation.md capabilities. Post-export gate:
re-open the package in a fresh process (validate_product_package /
definition materialization) and confirm definition/solid counts; list every
produced file with size.
Final delivery ⛔: evidence pack + artifact list + assumptions made + checks not run, and record the user's verdict. A rejection here routes back through the role map to the owning artifact.
Failure routes
- Boolean fails or yields multiple bodies →
domains/part-modeling.mdboolean discipline (overlap, overshoot tools, isolate the pair). - Fillet/chamfer fails → smaller radius, narrower selection, later order; selection problems follow the edge-selection defaults.
- Dimension mismatch → re-measure against
REQUIREMENTS.md; fix the named parameter, not the symptom. - Repeated dead ends →
discipline/failure-and-repair.md; reconsider the BUILD_PLAN stage, not the same retry.
Part source file, REQUIREMENTS.md, BUILD_PLAN.md with stage output
boundaries, verifier contracts, executable verification scripts, modeling
hypotheses, and method proofs; evidence pack paths; image verdicts quoted
from isolated subagent reviews; package/exports with sizes; assumptions made;
and checks not run.