forgecad 0.9.16 → 0.10.0

package/dist/docs-raw/skills/forgecad-blockout-model.md

@@ -1,3 +1,5 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-blockout-model/SKILL.md instead. -->
+
 # forgecad-blockout-model
 
 Create rough high-level ForgeCAD concept models from simple primitives to explore layout, proportions, motion, and part relationships without production detail. Use when asked for a quick model sketch, blockout, spatial mockup, or intuitive low-detail 3D concept.
@@ -11,25 +13,7 @@ Create rough high-level ForgeCAD concept models from simple primitives to explor
 
 ## Block Out a Model
 
-Create lightweight ForgeCAD concept models. These are spatial planning artifacts: fast, legible, and intentionally approximate, but still grounded in the physical object rather than an annotated lesson diagram.
-
-### Trigger Boundary
-
-Use this skill when the user wants to answer questions like:
-
-- Roughly where do the parts go?
-- Does this mechanism idea make intuitive spatial sense?
-- What is the silhouette, footprint, or motion envelope?
-- Can we show the concept before spending time on detail?
-
-Do **not** use this skill for:
-
-- print-ready or fabrication-ready geometry
-- exact fit, tight tolerances, or detailed dimensioning
-- dense parametric modeling
-- hardware details, fillets, chamfers, or finish work unless they are essential to the concept
-
-Routing:
+A blockout is a spatial planning artifact: 3-7 simple masses that answer where parts go, whether a mechanism makes spatial sense, and what the silhouette, footprint, or motion envelope looks like. Not for print-ready geometry, exact fit, tolerances, or detail work.
 
 | Need | Skill |
 |------|-------|
@@ -37,110 +21,29 @@ Routing:
 | Written concept or architecture before CAD | `forgecad-high-level-spec` |
 | Accurate, detailed, parametric ForgeCAD model | `forgecad-make-a-model` |
 
-### File Placement
-
-All new `.forge.js` files go under the date-based directory structure:
-
-```text
-YYYY/MM/DD/file.forge.js          - single-file blockout
-YYYY/MM/DD/folder/file.forge.js   - multi-file concept project
-```
-
-Use today's date for the directory. Use the user's current ForgeCAD project when one is available; otherwise use a clearly named local model folder.
-
-#### Naming
-
-- Use kebab-case
-- Prefer names like `desk-lamp-blockout.forge.js` or `hinged-display-concept.forge.js`
-- Add `-blockout` or `-concept` unless the user already supplied a clearer name
-
-### Workflow
-
-1. **Load the `forgecad` skill first** and read the Core API and CLI docs. Only load more documentation if the concept truly needs it.
-2. **Translate the idea into 3-7 conceptual parts** before writing geometry. Think in terms of masses and zones: base, arm, payload, sweep volume, keep-out space, hand access, wheel envelope.
-3. **Choose approximate dimensions** using round numbers and obvious proportions. Favor "believably shaped" over "numerically correct".
-4. **Write the simplest geometry that communicates the idea**. Default to `box()`, `cylinder()`, `sphere()`, and very simple extrusions.
-5. **Place parts with readable transforms**. Keep coordinates easy to inspect and edit. Prefer centered primitives when that reduces mental load.
-6. **Color by meaning** so a viewer can decode the concept immediately.
-7. **Render and inspect** from a few angles. If the idea is still unclear, simplify or reposition; do not add detail as a substitute for clarity.
-8. **Stop early** once the mechanism, layout, or concept is understandable.
+### Method
 
-### Modeling Rules
+- Load the `forgecad` skill first; read its Core API and CLI docs. Load nothing else unless the concept demands it.
+- Translate the idea into 3-7 conceptual parts BEFORE writing geometry: masses and zones (base, arm, payload, sweep volume, keep-out, hand access).
+- One primitive stands in for many eventual details. A bounding box beats a fake detailed part. Never add detail as a substitute for clarity — simplify or reposition instead.
+- Use round-number dimensions; "believably shaped" beats numerically correct. Name uncertainty honestly: `armLengthGuess`, `baseWidthApprox`, `clearanceEnvelope`.
+- At most a handful of `param()` values, for comparing proportions. Do not parameterize every dimension.
+- Color by meaning; keep each conceptual part visually distinct via color or opacity. Return named shape objects so the viewer can inspect the concept part-by-part.
+- Ghost geometry: transparent volumes only for REAL physical envelopes — sweep arcs, keep-out volumes, approximate payloads, reach/access zones. Never decorative teaching overlays. Exaggerate tiny clearances when needed for readability.
+- Even a blockout represents the object in its normal assembled state: no labels, legends, cutaways, or permanently exploded layouts (full rule in the `forgecad` skill).
+- Leave out: fasteners and screw holes, wall thicknesses, fillets and blend radii, polished materials, hidden internal structure that does not affect the concept.
 
-- Use one primitive to stand in for many eventual details whenever possible.
-- A bounding box is usually better than a fake detailed part.
-- Use at most a handful of top-level `param()` values when comparing rough proportions. Do not parameterize every dimension.
-- Name uncertainty honestly: `armLengthGuess`, `baseWidthApprox`, `screenVolume`, `clearanceEnvelope`.
-- Do not add text labels, callout arrows, legends, coordinate labels, or explanatory plaques to the model. Use named return objects and a short written note outside the geometry.
-- Do not cut away a shell, remove covers, or permanently explode parts just to show hidden intent. Even a blockout should represent the object in its normal assembled state unless the user explicitly asks for a presentation view.
-- Use transparent ghost geometry for:
-  - sweep arcs
-  - keep-out volumes
-  - approximate payloads
-  - user reach or access space
-- Ghost geometry must represent a real physical envelope, clearance, motion path, or human-access zone, not decorative teaching overlays.
-- Exaggerate tiny clearances if needed to keep the concept readable.
-- Keep each conceptual part visually distinct through color or opacity.
-- Prefer arrays of named shapes in the return value so the viewer can inspect the concept part-by-part.
+### Verify
 
-### What to Leave Out
-
-Do not spend time on:
-
-- screw holes
-- exact wall thicknesses
-- blend radii
-- polished materials
-- hidden internal structure that does not affect the concept
-- mathematical precision that the concept does not justify
-
-If you notice yourself reaching for detailed constraints, pause and ask whether the blockout should instead hand off to `forgecad-make-a-model`.
-
-### Render-Verify Loop
-
-Even rough models must be rendered. The whole point is spatial intuition.
-
-#### Minimum check
-
-```bash
-forgecad run model.forge.js
-node dist-cli/forgecad.js render model.forge.js /tmp/blockout.png --camera 45:25 --camera 0:0 --camera 90:0 --size 600
-```
-
-Inspect the render and ask:
+Rendering is mandatory even for rough models. Run the script, then render from 2-3 angles with the installed `forgecad` CLI (syntax: the `forgecad` skill's CLI docs). Judge by the reader test:
 
 - Can someone unfamiliar with the idea tell what each mass represents?
-- Are the overall proportions believable enough to discuss?
+- Are proportions believable enough to discuss?
 - Is motion or interference visible where it matters?
-- Are unknowns shown honestly, rather than hidden behind fake detail?
-
-If the answer is no, simplify the model or add clearer ghost volumes.
-
-### Useful Pattern
-
-```js
-// Concept only:
-// - dimensions are approximate
-// - red transparent geometry shows motion / keep-out
-
-const base = box(160, 90, 30).placeReference('center', [0, 0, 0]).color('#4c6ef5');
-const arm = box(22, 22, 180).placeReference('center', [0, 0, 105]).color('#f08c00');
-const payload = box(120, 18, 70).placeReference('center', [0, 0, 210]).color('#2b8a3e');
-
-const sweep = cylinder(12, 110, 110, 48).placeReference('center', [0, 0, 0])
-  .rotateY(90)
-  .translate(0, 0, 120)
-  .color('#e03131')
-  .material({ opacity: 0.18 });
+- Are unknowns shown honestly, not hidden behind fake detail?
 
-return [
-  { name: 'Base', shape: base },
-  { name: 'Arm', shape: arm },
-  { name: 'Payload Volume', shape: payload },
-  { name: 'Sweep Envelope', shape: sweep },
-];
-```
+If any answer is no, simplify or add clearer ghost volumes.
 
-### Handoff Rule
+### Handoff
 
-When the blockout has answered the high-level questions, stop. If the next question is about real fit, tunable dimensions, part details, or manufacturing logic, switch to `forgecad-make-a-model` rather than refining the blockout indefinitely.
+File placement and naming follow `forgecad-make-a-model` conventions; suffix the filename `-blockout` or `-concept` unless the user supplied a clearer name. Once the high-level questions are answered, stop. If the next question is real fit, tunable dimensions, part details, or manufacturing logic, switch to `forgecad-make-a-model` instead of refining the blockout indefinitely.

package/dist/docs-raw/skills/forgecad-component-model.md

@@ -1,3 +1,5 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-component-model/SKILL.md instead. -->
+
 # forgecad-component-model
 
 Enforce the ForgeCAD Component Model when building multi-part assemblies. Parts build at origin, connectors position them, data flows down from parent. Use when building or reviewing any multi-file ForgeCAD project.
@@ -9,129 +11,43 @@ Enforce the ForgeCAD Component Model when building multi-part assemblies. Parts
 
 ---
 
-## Component Model — The React of CAD
-
-You are building a ForgeCAD multi-part assembly. Follow the Component Model strictly.
-
-### The Core Principle
-
-**Parts never position themselves. The assembly positions them via connectors.**
-
-A part is a function from props to `{ shape, connectors, metadata }`. It builds at origin in local space. It doesn't know where it sits in the world.
-
-### Rules (Non-Negotiable)
-
-#### 1. Parts Build at Origin
-- Geometry starts at `[0, 0, 0]` in local coordinates
-- No assembly-space offsets (no `translate(pinionPitchR, 0, layout.pinionZ)`)
-- Internal structure computed from the part's own props only
-
-#### 2. Connectors Are the Interface
-- Every part that joins an assembly declares connectors via `.withConnectors({})`
-- A connector = origin + axis (outward from the part)
-- Connectors meet **face-to-face**: both axes point outward, system brings them together
-- For prismatic joints: axes point along the shared slide direction
-- Mirrored revolute axes need negated physical joint values for the same mirrored pose
-
-#### 3. Assembly Is Pure Composition
-- Use `addPart()` + `connect()` for frame-aware serial assemblies
-- Use `link()` + `edgeBetweenLinks()` + `addAngleBetweenLinks()` for solved point skeletons
-- Zero `translate()` calls for structural parts
-- Zero coordinate math
-- The assembly passes props down and reads metadata up
-
-#### 4. Data Flows Down, Never Sideways
-- **Props down:** Assembly passes dimensions to parts via `require('./part.forge.js', { Height: 20 })`
-- **Metadata up:** Parts return `{ shape, boltPattern, pinionZ, ... }` — computed values the parent might pass to siblings
-- **Siblings never import each other.** The assembly mediates ALL sibling communication
-
-#### 5. Verify, Don't console.log
-- Use `verify.that("name", () => condition)` for spatial checks
-- Use `verify.equal()`, `verify.inRange()`, `verify.notColliding()` for specific assertions
-- Never `console.log` + `if` for validation
-
-### Connector Convention
-
-```js
-// Face-to-face: both point outward, system opposes them
-base.withConnectors({
-  mount_face: connector("bolt-face", { origin: [0, 0, 0], axis: [0, 0, -1] }),
-  //                                  ↑ bottom face          ↑ faces downward
-});
-mount.withConnectors({
-  flange: connector("bolt-face", { origin: [0, 0, 0], axis: [0, 0, 1] }),
-  //                              ↑ top face            ↑ faces upward
-});
-
-// Assembly — no flip, no coordinate math
-assembly.connect("Base.mount_face", "Mount.flange", { as: "mount-fix" });
-```
+## Component Model
 
-Revolute values are signed by the physical hinge axis. In a bilateral mechanism,
-`axis: [1, 0, 0]` on the right side and `axis: [-1, 0, 0]` on the left side are
-exact mirrors at rest, but the same `+theta` value rotates them in opposite
-fore/aft senses. Use `Right: +theta`, `Left: -theta`, and mirror physical limits
-as `[min, max] -> [-max, -min]`, or drive both sides from a side-neutral link
-graph/control layer.
+The React of CAD: a part is a function from props to `{ shape, connectors, metadata }`, built at origin in local space. Parts never position themselves — the assembly positions them via connectors.
 
-### Part Return Shape
+### Rules
 
-Every part file returns a structured object:
+1. **Parts build at origin.** Geometry starts at `[0,0,0]` in local coordinates; no assembly-space offsets; internal structure derives from the part's own props only.
+2. **Connectors are the only interface.** Declare via `.withConnectors({})`; axes point outward, mating is face-to-face (exception: prismatic joints share a co-directional slide axis). Mechanics: the forgecad skill's `docs/guides/positioning.md` and `docs/generated/assembly.md`.
+3. **Assembly is pure composition.** Zero `translate()` to position structural parts, zero coordinate math — connect connectors, pass props down, read metadata up.
+4. **Data flows down, never sideways.** Props down via `require('./part.forge.js', { Height: 20 })` overrides; metadata up via the part's return object; siblings NEVER import each other — the assembly mediates all sibling communication.
+5. **Validate with `verify.*`, never `console.log` + `if`.**
 
-```js
-return {
-  shape: body.color('#708090').withConnectors({ ... }),
-  // Public metadata — parent may pass to siblings:
-  boltPattern,    // bolt positions for sibling parts
-  pinionZ,        // Z center for gear alignment
-  armWidth,       // arm cross-section for cover plate slots
-};
-```
-
-### File Structure
-
-**Default: one file for project-specific assemblies.** Parts are sections within the file. Shared data is variables. Split into separate files only when parts are reusable or the file exceeds ~300 lines.
+### Part return shape
 
 ```js
-// ─── Motor Mount ────────────────────────────
-const mount = buildMount({ servo, wall, clearance });
-
-// ─── Base Body ──────────────────────────────
-const base = buildBase({ gears, depth, height, boltPattern: mount.boltPattern });
-
-// ─── Assembly ───────────────────────────────
-assembly("Gripper")
-  .addPart("Base", base.shape)
-  .addPart("Mount", mount.shape)
-  .connect("Base.mount_face", "Mount.flange", { as: "fix" })
+return { shape, boltPattern, pinionZ }; // shape + metadata the parent may route to siblings
 ```
 
-### Anti-Patterns (Reject These)
-
-❌ **shared-dims.js** — A file whose only job is computing derived dimensions. The assembly should derive and pass them.
-
-❌ **Sibling imports** — `require('./motor-mount.forge.js')` inside `cover-plate.forge.js`. Data flows through the parent.
+### File structure
 
-❌ **Assembly-space coordinates in parts** — A part knowing `pinionZ = 14` from a sibling's geometry. It should receive `rackZ: 14` as a prop.
+Default: ONE file per project-specific assembly — parts as sections, shared data as variables. Split only for cross-project reuse or past ~300 lines. Never split for "organization".
 
-❌ **`translate()` in assembly** — If you're translating to position a part, add a connector instead.
+### Anti-patterns (reject on review)
 
-❌ **console.log validation** — Use `verify.*`. Always.
+- `shared-dims.js` — a file that only computes derived dimensions; the assembly derives and passes them.
+- Sibling `require()` — e.g. `require('./motor-mount.forge.js')` inside `cover-plate.forge.js`; route through the parent.
+- Assembly-space coordinates inside a part — a part knowing `pinionZ = 14` from a sibling's geometry; receive it as a prop.
+- `translate()` to position a structural part in an assembly — add a connector instead.
+- `console.log` + `if` validation — use `verify.*`.
+- Bare `connector.neutral()` outside a reusable component library with compatibility checking.
 
-❌ **Bare `connector.neutral()`** — Use `connector()` without gender unless building a reusable component library with compatibility checking.
+### Design gate
 
-### Design Gate
-
-Before committing any multi-part assembly, verify:
+Before committing any multi-part assembly:
 
 1. Can you understand each part without reading other files?
 2. Does the assembly contain zero coordinate math?
 3. Do all inter-part relationships flow through connectors and props?
 
 If any answer is no, refactor.
-
-### Reference
-
-Full philosophy: `docs/permanent/component-model.md`
-Connector details: `docs/permanent/generated/assembly.md`
-Blueprint-first: `docs/permanent/blueprint-first.md`

package/dist/docs-raw/skills/forgecad-high-level-spec.md

@@ -1,3 +1,5 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-high-level-spec/SKILL.md instead. -->
+
 # forgecad-high-level-spec
 
 Write a high-level design document (HLD) for a model, mechanism, or assembly before detailed specification or coding. Use when starting a new design, rethinking an existing one, or when the user asks to spec out, plan, or think through a model at a high level. Works backwards from requirements — defines the problem, explores alternatives, records decisions. Produces a right-sized design document for review and iteration.
@@ -11,199 +13,89 @@ Write a high-level design document (HLD) for a model, mechanism, or assembly bef
 
 ## High-Level Design (HLD)
 
-Write a right-sized design document that works backwards from requirements. Define the problem, explore the solution space, record decisions. Include as much detail as needed for quality and shared understanding; stop before exhaustive construction details.
-
-### Philosophy
-
-An HLD is a thinking tool, not a construction document. It should be:
-
-- **Quality-first and right-sized.** Use whatever detail, evidence, diagrams, dimensions, and examples are needed for a good decision.
-- **Honest about what's unknown.** Open questions are features, not bugs.
-- **Opinionated about alternatives.** Don't just list options — recommend one and say why.
-- **Stable under iteration.** Easy to update after a round of feedback without rewriting everything.
-
-Brevity is a readability tool, not a success metric. Do not omit visible evidence, image-derived features, assumptions, interfaces, risks, or decision-driving dimensions just to keep the document short.
-
-The HLD exists so that the user and the agent can align on *what* to build before anyone thinks about *how* to build it. All design concerns, risks, and tradeoffs live here — not in conversation, not in the agent's head.
-
-Manufacturing process is part of the design problem, not a default.
-If the user has not specified a process, compare plausible approaches and recommend the one that fits the artifact, load path, scale, material needs, safety expectations, and intended use.
-Do not default to 3D printing, FDM, or "printable" unless the user asked for it or the chosen concept genuinely calls for printed parts.
+The HLD aligns the user and the agent on *what* to build before anyone thinks about *how*. Every design concern, risk, and tradeoff lives in the document — not in conversation, not in the agent's head. Brevity is a readability tool, not a success metric: there is no page limit; include whatever evidence, diagrams, and dimensions a good decision needs. Decision-driving dimensions belong here; exhaustive construction dimensions belong in the LLD.
 
-### When to Write an HLD
+Manufacturing process is a design decision, not a default — never assume 3D printing/FDM. If the user didn't specify a process, treat process choice as an HLD alternative (full posture taxonomy: `/forgecad-prepare-prompt`).
 
-- Before starting a new model, mechanism, or assembly
-- When an existing design has fundamental problems (wrong approach, not just wrong numbers)
-- When the user says "spec this out", "think this through", "what should we build"
-- Before writing an LLD
-
-### Output Location
-
-HLDs go next to the model files. Name: `<name>-hld.md` or for a project: `hld.md` in the project folder.
+Write an HLD before any LLD, and whenever an existing design is wrong in approach, not just in numbers. Output: `<name>-hld.md` beside the model files, or `hld.md` for a whole project.
 
 ### Document Structure
 
+The section order is the workflow — write it top to bottom, following the embedded instructions.
+
 ```markdown
 # [Name] — High-Level Design
 
 ## Problem
-
-What does this need to do? What role does it play? What are the hard
-requirements (must grip objects, must fit in a 60mm housing, must use
-sheet metal, must be CNC-machinable, must be printable, must use purchased
-bearings)?
-
-State the problem without implying a solution.
+What must this do? Hard requirements (must grip objects, fit a 60mm
+housing, use purchased bearings). State the problem without implying
+a solution. Unspecified process choice is an open design dimension.
 
 ## Approach
-
-How does it work at a conceptual level? Describe the mechanism, structure,
-or behavior. Use ASCII diagrams where they make spatial relationships clearer.
-
-Keep this at the architecture level, but include enough spatial and behavioral
-detail that someone unfamiliar with the project understands the concept.
+How it works at a conceptual level. ASCII diagram of the key elements
+and their spatial relationships — diagram labels stay in this markdown;
+never carry them into CAD geometry unless the real artifact needs
+markings.
 
 ## Key Interfaces
-
-How does this connect to the rest of the system? What are the mating
-surfaces, shared dimensions, or coordination points? List them explicitly.
+Every point where this touches another part or the outside world:
+mating surfaces, shared dimensions, coordination points. These are the
+contracts that constrain the design.
 
 ## Dictionary
-
-Define every domain-specific term used in this document. Don't assume
-engineering terminology is widely known — write for a developer who
-doesn't have a mechanical engineering background.
-
 | Term | What it is |
 |------|-----------|
-| ... | Plain-language description with dimensions if relevant |
+Define every domain term in plain words, with dimensions where relevant.
+Write for a developer without a mechanical-engineering background.
 
 ## Alternatives
-
 | Option | Description | Tradeoff |
 |--------|-------------|----------|
-| A (recommended) | ... | ... |
-| B | ... | ... |
-| C | ... | ... |
-
-For each alternative, include enough detail to understand why it fits or loses.
-One sentence is fine only when one sentence is enough. Mark the recommended option.
+2-3 genuinely different strategies, not minor variations. Enough detail
+per row to see why it fits or loses. Mark one recommended and say why.
+If there is honestly only one approach, say so and skip the table.
 
 ## Usage Guide
-
-Work backwards from the user experience. Write the step-by-step needed to show
-how someone would use/assemble/operate this thing. This exposes gaps in the
-design before any code is written.
-
-For a physical product: assembly steps, tools needed, what connects to what.
-For a mechanism: how it moves, what the user does, what happens.
-For a software component: how it's called, what it returns, error cases.
-
-Flag issues inline with ⚠️.
+The strongest validation: work backwards from how someone uses,
+assembles, or operates the thing, step by step (physical product:
+assembly steps, tools, what connects to what; mechanism: how it moves
+and what the user does). If a step doesn't make sense ("how does the
+servo get inside?"), the design has a gap — flag it inline with ⚠️ and
+promote it to Concerns.
 
 ## Concerns
-
-Numbered list. Each concern is a risk, open question, or thing that
-could go wrong. Be specific — "tolerances might be tight" is useless;
-"the 12mm arm cantilevers under gripping load, may flex >0.5mm" is useful.
-
-Include issues discovered while writing the Usage Guide.
-
-1. ...
-2. ...
+1. Numbered, falsifiably specific — a reviewer must be able to say
+   "real problem" or "fine, because…". "Tolerances might be tight" is
+   useless; "the 12mm arm cantilevers under gripping load, may flex
+   >0.5mm" is useful.
 
 ## Decisions
-
-Filled in after review. Each decision references which concern or
-alternative it resolves.
-
 | # | Decision | Rationale |
 |---|----------|-----------|
-| 1 | ... | ... |
+Filled ONLY after user review — never pre-decide. Each row resolves a
+concern or alternative.
 ```
 
-### Workflow
-
-#### 1. Define the problem
-
-State what the part/assembly needs to accomplish. Include hard constraints (size envelope, specified manufacturing/process constraints, interfaces with other parts). Do not describe a solution yet.
-If no process is specified, treat manufacturing/process choice as an HLD alternative rather than as a hidden assumption.
-
-#### 2. Sketch the approach
-
-Describe the recommended approach at a conceptual level. Draw an ASCII diagram showing the key elements and their spatial relationships. Label the markdown diagram, but do not carry those labels into CAD geometry unless the real artifact needs markings.
-
-#### 3. Identify interfaces
-
-List every point where this design touches another part or the outside world. These are the contracts that constrain the design.
-
-#### 4. Explore alternatives
-
-Show 2-3 meaningfully different approaches. Not minor variations — genuinely different strategies. For each, state the key tradeoff in one line. Recommend one.
-
-#### 5. Write the usage guide
-
-Work backwards: describe how someone uses/assembles/operates this thing step by step. This is the most powerful validation — it forces you to think through the physical reality before writing code. If a step doesn't make sense ("how does the servo get inside?"), the design has a gap.
-
-Flag issues inline with ⚠️. These feed directly into the Concerns list.
-
-#### 6. Surface concerns
+### Review via git
 
-Collect everything from the usage guide ⚠️ flags plus any risks, open questions, or things that could go wrong. Be concrete and specific. These are the agenda for the review conversation.
+HLDs and LLDs iterate through git, not conversation:
 
-#### 7. Commit and present for review
+- **Commit every version.** No drafts floating in chat. After writing, commit and tell the user it's ready for review.
+- **Feedback arrives as file edits** (inline comments, strikethroughs) **or chat — check both.** Read `git diff`: the diff is the review artifact.
+- **Update, commit, repeat** until the Decisions table is filled and the user says "go."
 
-Commit the HLD to git. Tell the user it's ready for review. Do NOT fill in the Decisions table yet.
+### Rules
 
-#### 8. Iterate via git
+- If you're speccing every part, formula, tolerance, and fabrication step, you're writing an LLD — back up.
+- If you can't draw it, you don't understand it yet.
+- Tables are welcome where they clarify (interfaces, requirements, visible evidence); full parameter catalogs go to the LLD.
 
-The user reviews the file (may edit it directly with comments/strikethroughs, or give verbal feedback). After review:
-
-1. Read the git diff or the updated file to see the user's feedback
-2. Update the HLD to address feedback
-3. Commit the update
-4. Present for another round if needed
-
-Repeat until the Decisions table is filled and the user says "go."
-
-### Git Workflow
-
-HLDs and LLDs iterate through git, not conversation. This keeps the document as the single source of truth and gives both sides a clear diff to review.
-
-```
-Agent writes HLD → git commit → User reviews (edits file or gives feedback)
-→ Agent reads diff → updates HLD → git commit → repeat until approved
-```
-
-- **Every version gets committed.** No unsaved drafts floating in conversation.
-- **User feedback goes in the file** (inline comments, strikethroughs) or in chat — agent checks both.
-- **The diff is the review artifact.** Agent reads `git diff` to see what changed.
-
-### Writing Rules
-
-- **Quality first.** There is no fixed page, time, or section-length limit. Write the HLD to the depth the design deserves.
-- **Clear, not artificially terse.** If a reviewer has to re-read a paragraph to understand it, rewrite it; do not delete needed content just to make it shorter.
-- **ASCII diagrams where useful.** A cross-section sketch can communicate layout better than paragraphs, but use whichever representation makes the design clearest.
-- **Decision-driving dimensions are welcome.** Include dimensions, size envelopes, counts, interface dimensions, and proportional constraints when they clarify architecture, risks, image matching, or feasibility. Put exhaustive construction dimensions and formulas in the LLD.
-- **Tables are allowed when they improve clarity.** Use compact tables for alternatives, interfaces, requirements, feature inventories, or visible evidence. Keep full parameter catalogs in the LLD.
-- **Concerns are not rhetorical.** Every concern must be specific enough that someone can say "yes that's a real problem" or "no, here's why it's fine."
-- **Alternatives are not padding.** If there's genuinely only one way to do it, say so and skip the table.
-
-### Relationship to Other Skills
+### Pipeline
 
 | Stage | Skill | Output |
 |-------|-------|--------|
-| 1. Explore the problem space | `/forgecad-high-level-spec` (this skill) | `*-hld.md` |
+| 1. Explore the problem space | this skill | `*-hld.md` |
 | 2. Detailed design | `/forgecad-lld` | `*-lld.md` |
-| 3. Implementation | `/forgecad-make-a-model` + `/forgecad` | `.forge.js` files |
-
-The HLD must have its Decisions table filled before writing an LLD. The LLD must exist before implementation (unless the model is simple enough to skip straight from HLD to code).
-
-### Anti-Patterns
+| 3. Implementation | `/forgecad-make-a-model` + `/forgecad` | `.forge.js` |
 
-- **HLD that's actually an LLD.** If you're exhaustively specifying every part, formula, tolerance, and fabrication step before the architecture is chosen, you've gone too far. Back up.
-- **HLD with no alternatives.** You haven't explored the solution space. Even if the answer is obvious, name what you rejected and why.
-- **Concerns that are vague worries.** "This might be hard to manufacture" — hard how? Tool access? Bending radius? Wall thickness? Tolerance stack? Support material? Be specific or don't list it.
-- **Decisions made before review.** The whole point is to align with the user before committing. Present the HLD, discuss, then decide.
-- **Skipping the diagram.** If you can't draw it, you don't understand it yet.
-- **Iterating in conversation instead of in the file.** The document is the artifact. Update it, commit it, review the diff.
+The Decisions table must be filled before writing the LLD. Simple models may skip straight from HLD to code.