v0.2.2

Architecture

How the Form & Force repository is organised, why, and how its parts depend on each other. For how the method works, see how it works.

The product in one paragraph

Form & Force is a skill: a folder an agent loads, holding an operating manual, a library of references, a set of templates and a set of command-line instruments. Everything else in this repository exists to justify that folder (research), to prove it works (tests and evaluations), to deliver it (plugin manifests and packaging), to explain it (documentation and the site), or to present it (the brand). The repository is organised around that fact: one product at the centre, and around it the things that serve it, each in its own place.

Conceptual architecture

                    ┌──────────────────────────── the skill (ships) ────────────────────────────┐
                    │  skills/form-and-force/                                                   │
                    │    SKILL.md ............ method: the stages, what to load, when to stop    │
                    │    references/ ......... knowledge: method, craft, motion, components,     │
                    │                          engineering (18 files, flat, linked from SKILL.md) │
                    │    assets/ ............. templates the agent fills in (5)                  │
                    │    scripts/ ............ instruments: 8 Node tools, 2 modules, the deck     │
                    └────────────────────────────────────────────────────────────────────────────┘
        evidence ▲              ▲ verification            ▲ delivery              ▲ explanation & identity
   research/     │   tests/  evals/                .claude-plugin/          docs/  site/  brand/
   why it says   │   free checks · browser         plugin + marketplace;    Markdown pages, the
   what it says  │   checks · paid model evals     tooling/package_skill    site built from them,
                 │   (human judgement: protocols)  builds the ZIP           the identity
                 └──────────────── tooling/ : the maintainer's workshop (Python, standard library) ─────┘
DomainDirectoryResponsibilityShips to users
The skillskills/form-and-force/The method, the knowledge, the templates and the tools an agent usesYes: in the plugin and the ZIP
Delivery.claude-plugin/The plugin manifest, the one-plugin marketplace, the listing iconYes: in the plugin
Evidenceresearch/Sources, measurements and reasoning behind every rule; what could not be establishedNo
Verificationtests/, evals/Free deterministic and browser tests; paid, opt-in model evaluations with their fixturesNo
Documentationdocs/, root *.mdGuides, references, development and project documents, readable on GitHubNo
Sitesite/Builds the documentation website from the MarkdownNo (published separately, by hand)
Identitybrand/The brand system: sources, guidelines, generated assetsNo (used by the README, site and plugin listing)
Workshoptooling/Validation, packaging, the release gate, eval wrappers, link audit, documentation syncNo

Inside the skill

The skill's layout follows the Agent Skills specification (SKILL.md, references/, scripts/, assets/), so it works unchanged as a plugin skill, a personal skill and an upload. Its four parts have distinct jobs:

  • The method is SKILL.md: an operating manual, not an encyclopedia (a test keeps it under about 4,500 tokens). It sizes the job, orders the stages, and routes each stage and task to the references it needs.
  • The knowledge is references/. It is flat on purpose: every file is one link from SKILL.md, files point at each other by section number (jury.md §8), and the agent's search commands assume one directory. The grouping (method, craft, motion, components, engineering) is documented in the reference library rather than imposed as folders. The component atlas is one file because it is searched with grep, one entry at a time.
  • The instruments are scripts/. Each does one job at one stage and keeps the same command-line contract. browser.mjs (Playwright resolution and rendering) and design_facts.mjs (page measurement) are shared modules; deck.json is the dealer's data.
  • The templates are assets/, the specification's name for files an agent fills in.

Dependencies

Dependencies run one way: toward the skill, never out of it.

skills/form-and-force  ◄── tooling/ (validates and packages it)
        ▲  ▲  ▲        ◄── tests/  (runs its tools; checks its documents)
        │  │  │        ◄── evals/  (`claude plugin eval` loads it as a plugin)
        │  │  └──────────── site/   (renders its Markdown as pages)
        │  └─────────────── brand/build.mjs (reuses scripts/browser.mjs to render rasters)
        └────────────────── docs/   (explain it; generated tables read deck.json and the atlas)
brand/ ◄── site/ (tokens, fonts, logo, icons, backgrounds)     brand/ ◄── README, .claude-plugin/icon.png
  • The skill depends on nothing in the repository. It must run from a copied folder. A test (test_brand.py) also checks that it contains no brand colours or typefaces: the product's identity must never become a style it imposes on users' projects.
  • The brand depends on the skill only for browser.mjs, so the project has one way of finding a browser, not two.
  • The site depends on the brand, not the other way round, so a colour changes in one place.

Languages and runtime dependencies

PartLanguageDependenciesWhy
The skill's toolsJavaScript (Node 18+, ES modules)Node built-ins; Playwright for four tools, resolved at run time and never installedUsers install a folder, not a package. Agents already have Node
Repository tooling, tests, site builderPython 3.11+Standard library onlyA contributor needs only Python to run every required check
Brand rendererJavaScript (Node)Playwright, through browser.mjsRasters are rendered by a real browser, from SVG and HTML sources
Brand type preparationPythonfontTools, brotli, uharfbuzz in a virtual environmentRun rarely, by a maintainer; its outputs are committed

There is no package manager, lock file or build step in the repository. That is deliberate and is the main reason it has no package.json, apps/ or packages/: nothing here is a library that other code imports.

Sources of truth

Every fact that appears in more than one place has one owner, and a check that catches drift.

FactOwnerConsumersDrift is caught by
Version.claude-plugin/plugin.jsonSKILL.md metadata, pyproject.toml, CHANGELOG.md, the site headervalidate_repository.py (versions must agree)
The deckskills/form-and-force/scripts/deck.jsondeal.mjs, the deck referencetooling/sync_docs.py --check
The component atlasreferences/component-atlas.mdIts own index, the atlas reference, site searchtest_library.py, sync_docs.py --check
The tools' interfacesEach tool's header comment (its --help)SKILL.md, the tools referencetest_skill_scripts.py (contract), test_creative_method.py (routing)
Colours and typefacesbrand/source/tokens.jsonBrand files, the site's CSS, the colour guidetest_brand.py
The mark and wordmarkbrand/source/mark.json, wordmark.jsonEvery logo, icon and compositionnode brand/build.mjs --check
Media provenancebrand/manifest.json, ALLOWED_MEDIAThe validatorvalidate_repository.py
Site navigationsite/nav.jsonThe site's sidebar, URLs, pagersite/build.py (every docs/ page listed, every link resolves)

How things flow

At work, in an agent session. The agent reads SKILL.md, loads the references a stage needs, runs the tools from ${CLAUDE_SKILL_DIR}/scripts/, writes sketches to .ff/frames/ in the user's project and rendered evidence to the system's temporary directory, and records committed directions in ~/.form-and-force/history.json. Nothing leaves the machine.

Delivery. The repository root is both a plugin and a one-plugin marketplace (.claude-plugin/marketplace.json points at ./), so claude plugin marketplace add erenthedeveloper0/form-and-force and a local clone work the same way, and Claude Code discovers the skill at skills/form-and-force/. tooling/package_skill.py builds the standalone ZIP from the same folder, verifies it, and produces the same bytes every time.

Verification. Four kinds, kept apart (testing): deterministic checks run in CI on every pull request; browser checks run locally when Playwright is available; model evaluations run only when a person pays for them; human judgement is never automated and never reported as a test result.

Presentation. brand/build.mjs renders the identity from its sources; site/build.py renders the documentation, with the brand's tokens and fonts, into dist/site/, which a manual workflow can deploy.

Where to add things

To addPut it inGuide
Method or knowledge the agent usesskills/form-and-force/references/, routed from SKILL.mdExtending
A componentThe atlas, in its sectionExtending
A carddeck.jsonExtending
A toolskills/form-and-force/scripts/Extending
A check on the repositorytooling/validate_repository.py, with a test that breaks a copyContributing
An eval caseevals/<case>/Extending
A documentation pagedocs/, listed in site/nav.jsonExtending
A source or a measurementresearch/, recorded in the ledgerContributing
A brand assetbrand/build.mjsBrand and site

Decisions

Short records of choices that shape the repository, so they are not re-litigated by accident.

  • One product, not a monorepo. The skill is the only thing users install, and nothing here is imported by other code. A workspace of packages would add a package manager, a lock file and build steps without solving a problem.
  • Repository tooling in tooling/, not scripts/. The skill has a scripts/ folder by specification. A second scripts/ at the root, in another language and for another audience, made every path ambiguous. Renamed in the release after 0.2.1.
  • Brand in brand/, not assets/. assets/ is the specification's name for the skill's templates. The brand is a domain of its own, with sources, guidelines and generated files.
  • Flat references, one atlas file. Both are read by an agent with grep and section pointers. Folders would lengthen every pointer and split searches, for a grouping that documentation can show instead.
  • Documentation in Markdown, the site generated. Every page reads on GitHub; the site adds navigation and search without becoming a second copy.
  • A small Markdown renderer instead of a site generator. Keeps the "Python standard library only" rule for everything a contributor runs. It renders the Markdown this repository writes and fails loudly on anything it cannot resolve.
  • Provenance by hash for generated media. The validator must reject third-party images without blocking original artwork; recording each rendered file's hash makes "this came from build.mjs" checkable.
  • Paid evaluations never in CI. Every run is billed; the workflow validator rejects any workflow that would start one.