Extending Form & Force
How to add to each part of the project without breaking what depends on it. Read ARCHITECTURE.md first for where things live and why. Everything under skills/form-and-force/ ships to users; keep development notes out of it.
A reference
References are the skill's knowledge. The agent loads one only when SKILL.md routes a stage or a task to it.
- Decide whether it is new. Most new guidance belongs in an existing reference. A new file is justified when a topic has its own stage or its own kind of task, and would otherwise make another reference serve two purposes.
- Write it in
skills/form-and-force/references/<name>.md, lower-case with hyphens:- a one-paragraph opening that says what it is for and when to read it;
- numbered sections (
## 1. Title), so other files can point at them; - a
## Contentslist that matches the sections, if it runs over 100 lines; - questions and principles, not answers: no example palettes, typeface pairings or token values;
- claims that trace to the research ledger, or that say they are reasoned.
- Route to it from
SKILL.md: link it in the stage that needs it, and add it to the "Load only what the task needs" table if a task should load or skip it. The validator fails a reference thatSKILL.mddoes not link. KeepSKILL.mdunder its token budget (a test fails past about 4,500 tokens); move detail into the reference, not the manual. - Point at sections from other files as
name.md §N. A test resolves every pointer. - Add it to the site and the map: an entry in
site/nav.jsonunder "The skill", and a row in docs/reference/library.md. - Check:
python3 tooling/validate_repository.py,python3 -m unittest discover -s tests,python3 site/build.py --check,python3 tooling/package_skill.py.
An atlas entry
- Find the section in
component-atlas.md(§1–§12) where the component's job belongs, and check the name is not taken:grep -n "^### " skills/form-and-force/references/component-atlas.md. - Copy the field order of a neighbouring entry exactly: Job; Generic and Why it fails; Stronger; Keep convention when; Decide; Content, Motion, Responsive, A11y; States; Build; Test, Severity, Evidence; Example. Use
—for a field that genuinely does not apply, never omit it. - If another entry or reference already covers the component, write a one-line cross-reference instead:
- See "Entry name" (§N). … **Severity:** A. **Evidence:** …. - Severity starts with A (a review trigger) or C (a failure if violated). Evidence cites ledger IDs, corpus sections or references.
- "Stronger" lines are ways out to be re-derived from the project, never designs to copy. Do not name colours, typefaces or sizes.
- Add the name to the section's line in the atlas's Contents, in order, and update the counts.
tests/test_library.pychecks the index against the entries. - Run
python3 tooling/sync_docs.pyto regenerate the atlas index in the documentation.
A deck card
The deck (skills/form-and-force/scripts/deck.json) is the dealer's source.
- Lenses are questions. Give a lens an
id,family,name,ask(the question),answer(the form the answer takes),restraint(how it applies in a restrained register) andtrap. Optionalvariantsfill the{variant}slot in the question. - Structures (stored under
archetypes) are compositional principles:id,family,name,registers(the levels 1–4 that may be dealt it),principle,decideandrisk. - Never name a colour, a typeface or a size on a card: a test fails the deck if one appears.
- Never rename an id. Ids are stored in people's history files.
- Keep every register able to deal four structures from different families; a test checks it.
- Run
python3 tooling/sync_docs.pyto regenerate the deck reference.
A tool
- Write
skills/form-and-force/scripts/<name>.mjs: a#!/usr/bin/env nodeline, the SPDX line, and a header comment that is the usage (it is what--helpprints). - Node built-ins only. If it needs a browser, import
browser.mjsand let it resolve Playwright; never import Playwright statically, never install anything, and make no network calls beyond the URLs the user passes. Never read secret files. - Keep the command-line contract:
--helpand-hprint usage and exit 0 without side effects; usage errors and missing inputs exit 2 with a message that names the problem; a finding the tool exists to report may exit 1. - Route it from
SKILL.md's scripts table and the stage that uses it. A test fails if a tool is missing from the table. - Any question the tool can raise must be explained in
jury.mdormotion-craft.md; a test checks it. - Add tests in
tests/test_skill_scripts.py(ortest_rendered_tools.pyfor browser behaviour), and document it in the tools reference.
A template
Templates live in skills/form-and-force/assets/. Keep them to one screen where possible, link them from the stage in SKILL.md that uses them, add them to site/nav.json, and describe them in templates.
An eval case
- Create
evals/<case-name>/prompt.mdwith frontmatter that has adescription(and optionallyruns,max_turns,allowed_tools). - Add graders in
evals/<case-name>/graders/*.md, each with atypeofregex,tool_used,tool_order,file_exists,llmorbaseline. Prefer free grader types; everyllmorbaselinegrader is a billed call per run. - If the case needs files, add a
case.yamlnaming the directory and ascaffold_script, and a fixture underevals/fixtures/. A test checks that the scaffold reproduces the fixture exactly. - Run
python3 tooling/evals.py(free) to see what a run would cost. Do not run the paid suite in CI, and report a case as not run until it has been.
A documentation page
Write it in docs/, add it to site/nav.json in the right section, and link it from docs/README.md. The site build fails if a page under docs/ is not in the navigation, or if any link or anchor does not resolve. If the page repeats data that lives elsewhere, generate that part: add a block to tooling/sync_docs.py and mark it with <!-- generated:name --> … <!-- /generated -->.
A brand asset
Add the composition to brand/build.mjs, using only tokens from brand/source/tokens.json, and rebuild. The manifest records the new file's hash, which is what the validator accepts as provenance. See brand and site.