forgecad-design-spec

Name: forgecad-design-spec
Author: ForgeCAD

906stars102forks

How to install forgecad-design-spec?

forgecad/forgecad-public-kit/forgecad-design-spec

$npx -y skills add ForgeCAD/forgecad-public-kit --skill forgecad-design-spec

Installs into the current project.

Summary

Create a ForgeCAD design brief, HLD, or LLD before coding by walking through use, assembly, interfaces, decisions, and verification.

Files · 1

View on GitHub

SKILL.md

1	# Design Spec
2
3	The design document — a git-committed, diff-reviewed markdown file — is the source of truth. Not the code, not the chat, not your head. You iterate it by commit-and-review, and the `git diff` is the review artifact.
4
5	Validate the design by mentally operating the thing, step by step. Walk it as someone assembles, uses, or moves it. The step with no answer — "how does the servo get inside the housing?" — is the real design gap. A spec that reads complete on the page can still hide a hole that only surfaces when you try to put it together in your head. State each gap falsifiably: not "tolerances might be tight" but "the 12mm arm cantilevers under gripping load, may flex >0.5mm."
6
7	Every number has a reason; the narrative comes before the numbers. Describe the object as if over the phone, then derive each value and show its math: `wallThickness = 2.4mm = 6 × 0.4mm nozzle`. The design is implementation-blind — shaped by the object, never by what the ForgeCAD API makes easy. Manufacturing process is one of those reasons — a design decision you weigh, never a default you inherit (never assume FDM/printing).
8
9	A vague request is a set of decisions you make honestly, not information to extract. No placeholders ("appropriate motor"); choose a defensible value, show why, continue. The Decisions table fills only after user review, so the loop stays in the document.
10
11	## Altitude — three phases, one document trail
12
13	\| Phase \| When \| Output \|
14	\|-------\|------\|--------\|
15	\| Intake \| request is fuzzy / process unspecified \| engineering brief + master prompt \|
16	\| HLD \| design is wrong in approach, alternatives exist \| `<name>-hld.md` \|
17	\| LLD \| decisions locked, or a simple single-body part \| `<name>-lld.md` \|
18
19	The HLD carries only decision-driving dimensions and genuinely-different alternatives; the LLD carries enough that someone builds from it alone. Speccing every tolerance in an HLD, or revisiting locked decisions in an LLD, is an altitude error — back up. Simple parts skip straight from HLD to code, or from a request to an LLD.
20
21	---
22
23	## Phase 1 — Intake (fuzzy request → concrete brief)
24
25	Use when the user wants something physically real but the ask is vague ("make me a robot gripper", "make it production ready", "pick sensible numbers"). This phase owns intake; once the brief is concrete, continue to HLD or hand off to the `forgecad` skill.
26
27	Manufacturing is a design decision, not a default. Derive the process stack from artifact family, load path, scale, safety expectations, material, production intent, and operating story — never assume printing/plastic. If the user names a process, honor it but warn when it is unsafe or dishonest for the duty. Family→process anchors live in `references/default-profiles.md`.
28
29	Default posture: manufacture-realistic prototype — real materials, purchased-part boundaries, assembly logic, validation; no claims of production tooling or certification. Other postures only when justified: `production-realistic`, `printable`, `visual-CAD`, or a specific process posture (`sheet-metal`, `CNC-machined`, `laser-cut`, `welded-tube`, `injection-molded`, `cast`, `hybrid purchased-hardware`). Pick the posture honest for the artifact, not the easiest CAD surface.
30
31	Family-scoped numbers. Every starter assumption is scoped to one artifact family; never reuse numbers across families.
32
33	Workflow:
34	1. Normalize the ask into plain mechanism language ("6 DOF gripper" → standalone gripper, wrist+gripper, or arm+gripper).
35	2. Build a specific operating story — invented (non-famous) org, named program, prototype revision, review moment, mission pressure (pilot gate, demo date, investor milestone), and the generic failure mode to avoid. Prefer bold high-agency stories over modest lab exercises. Never assert the user works for a named real company; use real products only as public comparison anchors; never clone proprietary designs.
36	3. Classify the artifact family (`references/default-profiles.md`); use the no-family-fits escape rather than forcing one. Rideables route to human-vehicles, never chassis.
37	4. Choose the process posture per the taxonomy above.
38	5. Pick qualitative levers — duty (`light`/`general`/`sturdy`), scale (`compact`/`medium`/`large`), cost (`cheapest`/`balanced`/`performance-first`) — and translate to family-scoped starter assumptions.
39	6. Close only critical gaps — at most 3 grouped questions, always choice menus, never raw engineering inputs unless the architecture truly depends on them. Good: "light desk demo, useful hobby tool, or sturdier bench mechanism?" Bad: "What payload mass?"
40	7. Write the engineering brief: artifact + family + normalized interpretation; operating story + production reason + test setting + failure mode t

ForgeCADPublisher · 10 listings

Preview

ForgeCAD/forgecad-public-kit

# Design Spec

The design document — a git-committed, diff-reviewed markdown file — is the source of truth. Not the code, not the chat, not your head. You iterate it by commit

**Validate the design by mentally operating the thing, step by step.** Walk it as someone assembles, uses, or moves it. The step with no answer — *"how does the

**Every number has a reason; the narrative comes before the numbers.** Describe the object as if over the phone, then derive each value and show its math: `wall

RepoForgeCAD/forgecad-public-kit

LicenseMIT

TypeSkills

CategoryDesign

UpdatedJun 2026

Repo stars906

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type

forgecad-design-spec

906stars102forks

View on GitHub

How to install forgecad-design-spec?

forgecad/forgecad-public-kit/forgecad-design-spec

$npx -y skills add ForgeCAD/forgecad-public-kit --skill forgecad-design-spec

Installs into the current project.

Summary

Create a ForgeCAD design brief, HLD, or LLD before coding by walking through use, assembly, interfaces, decisions, and verification.

Files · 1

View on GitHub

SKILL.md

1	# Design Spec
2
3	The design document — a git-committed, diff-reviewed markdown file — is the source of truth. Not the code, not the chat, not your head. You iterate it by commit-and-review, and the `git diff` is the review artifact.
4
5	Validate the design by mentally operating the thing, step by step. Walk it as someone assembles, uses, or moves it. The step with no answer — "how does the servo get inside the housing?" — is the real design gap. A spec that reads complete on the page can still hide a hole that only surfaces when you try to put it together in your head. State each gap falsifiably: not "tolerances might be tight" but "the 12mm arm cantilevers under gripping load, may flex >0.5mm."
6
7	Every number has a reason; the narrative comes before the numbers. Describe the object as if over the phone, then derive each value and show its math: `wallThickness = 2.4mm = 6 × 0.4mm nozzle`. The design is implementation-blind — shaped by the object, never by what the ForgeCAD API makes easy. Manufacturing process is one of those reasons — a design decision you weigh, never a default you inherit (never assume FDM/printing).
8
9	A vague request is a set of decisions you make honestly, not information to extract. No placeholders ("appropriate motor"); choose a defensible value, show why, continue. The Decisions table fills only after user review, so the loop stays in the document.
10
11	## Altitude — three phases, one document trail
12
13	\| Phase \| When \| Output \|
14	\|-------\|------\|--------\|
15	\| Intake \| request is fuzzy / process unspecified \| engineering brief + master prompt \|
16	\| HLD \| design is wrong in approach, alternatives exist \| `<name>-hld.md` \|
17	\| LLD \| decisions locked, or a simple single-body part \| `<name>-lld.md` \|
18
19	The HLD carries only decision-driving dimensions and genuinely-different alternatives; the LLD carries enough that someone builds from it alone. Speccing every tolerance in an HLD, or revisiting locked decisions in an LLD, is an altitude error — back up. Simple parts skip straight from HLD to code, or from a request to an LLD.
20
21	---
22
23	## Phase 1 — Intake (fuzzy request → concrete brief)
24
25	Use when the user wants something physically real but the ask is vague ("make me a robot gripper", "make it production ready", "pick sensible numbers"). This phase owns intake; once the brief is concrete, continue to HLD or hand off to the `forgecad` skill.
26
27	Manufacturing is a design decision, not a default. Derive the process stack from artifact family, load path, scale, safety expectations, material, production intent, and operating story — never assume printing/plastic. If the user names a process, honor it but warn when it is unsafe or dishonest for the duty. Family→process anchors live in `references/default-profiles.md`.
28
29	Default posture: manufacture-realistic prototype — real materials, purchased-part boundaries, assembly logic, validation; no claims of production tooling or certification. Other postures only when justified: `production-realistic`, `printable`, `visual-CAD`, or a specific process posture (`sheet-metal`, `CNC-machined`, `laser-cut`, `welded-tube`, `injection-molded`, `cast`, `hybrid purchased-hardware`). Pick the posture honest for the artifact, not the easiest CAD surface.
30
31	Family-scoped numbers. Every starter assumption is scoped to one artifact family; never reuse numbers across families.
32
33	Workflow:
34	1. Normalize the ask into plain mechanism language ("6 DOF gripper" → standalone gripper, wrist+gripper, or arm+gripper).
35	2. Build a specific operating story — invented (non-famous) org, named program, prototype revision, review moment, mission pressure (pilot gate, demo date, investor milestone), and the generic failure mode to avoid. Prefer bold high-agency stories over modest lab exercises. Never assert the user works for a named real company; use real products only as public comparison anchors; never clone proprietary designs.
36	3. Classify the artifact family (`references/default-profiles.md`); use the no-family-fits escape rather than forcing one. Rideables route to human-vehicles, never chassis.
37	4. Choose the process posture per the taxonomy above.
38	5. Pick qualitative levers — duty (`light`/`general`/`sturdy`), scale (`compact`/`medium`/`large`), cost (`cheapest`/`balanced`/`performance-first`) — and translate to family-scoped starter assumptions.
39	6. Close only critical gaps — at most 3 grouped questions, always choice menus, never raw engineering inputs unless the architecture truly depends on them. Good: "light desk demo, useful hobby tool, or sturdier bench mechanism?" Bad: "What payload mass?"
40	7. Write the engineering brief: artifact + family + normalized interpretation; operating story + production reason + test setting + failure mode t

ForgeCADPublisher · 10 listings

Preview

ForgeCAD/forgecad-public-kit

# Design Spec

The design document — a git-committed, diff-reviewed markdown file — is the source of truth. Not the code, not the chat, not your head. You iterate it by commit

**Validate the design by mentally operating the thing, step by step.** Walk it as someone assembles, uses, or moves it. The step with no answer — *"how does the

**Every number has a reason; the narrative comes before the numbers.** Describe the object as if over the phone, then derive each value and show its math: `wall

RepoForgeCAD/forgecad-public-kit

LicenseMIT

TypeSkills

CategoryDesign

UpdatedJun 2026

Repo stars906

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type