Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
54 lines (33 loc) · 3.83 KB

CONTRIBUTING.md

File metadata and controls

54 lines (33 loc) · 3.83 KB
Raw

Contributing

Pick a good first issue, or open an issue with the problem you want to solve. Keep a pull request to one change and say how you checked it. Our code of conduct applies here.

New here? Your first contribution maps the starter issues to the files and checks they need. Documentation and synthetic proof tests do not need a model account.

Run the checks

Use Node.js 20 or newer (CI uses 22), Chrome or Chromium, and ffmpeg on your PATH. From the repo root:

npm ci
npx playwright-core install chromium ffmpeg
npm test

The Playwright install supplies Chromium and the recorder's ffmpeg. Motion exports also need the system ffmpeg. On Linux, install any browser system libraries Playwright reports as missing. If you already have Chrome or Edge, proof can use it. Set CHROME_PATH to use a particular executable.

npm test runs the proof, dashboard and runner tests, including installer and provider fixtures. It does not need a paid model call. If you have Claude Code installed, npm run validate also checks the plugin manifest.

Add a desk

A desk's source is one brief in skills/desk/roles/<slug>.md plus its entry in skills/desk/desks.json.

Use a nearby brief as a starting point. Say what the desk owns, what it needs before starting, how it decides, what it checks and the exact shape it returns. Keep its job distinct from the existing desks. The registry entry names the slug, name, tier, tools, turn cap, ownership and description. Use an existing tier and only the tools the desk needs. The Manager is the special entry with agent: false.

Then regenerate the files that read those sources:

node scripts/build-agents.mjs
node scripts/build-adapters.mjs
node site/readme.mjs
npm test

Commit the brief, registry entry and changed tracked outputs together. agents/, docs/roles.md and adapters/ are generated. The package copies made by build-adapters.mjs are ignored. README.md is generated by site/readme.mjs, so edit that script when changing README text. A registry entry makes a desk available, it does not add a new runner command. Command routing lives in runner/commands.mjs.

Rubric and proof

The rubric scores eight axes from rendered screenshots: hierarchy, typography, spacing, colour, composition, originality, brand fit and copy. Sign-off needs every axis at least 8 and the average at least 8.5. A score should have a render behind it.

Proof runs mechanical checks before sign-off. It checks rendered text and background pixels for contrast, canvas overflow, safe zones, fonts, type scale, palette and required copy. There are also email, slide-series and motion checks. It does not call a model and does not replace the visual rubric.

For a visual change, run proof at the sizes you changed and include its JSON result and renders in the pull request. For example, from the repo root with a local HTML file and brand file:

node proof/cli.mjs check path/to/final.html --brand path/to/DESIGN.md --sizes phone,desktop --out path/to/renders

Run node proof/cli.mjs sizes to see the size names. Report remaining failures and under-bar scores as they are. For a proof or runner fix, include a small regression case that fails before the fix and passes after it. For a brief or documentation change, explain which source and generated files you checked.

Agent adapters

Host instruction blocks come from scripts/build-adapters.mjs. The installer and its host paths live in packages/deskstudio/bin/deskstudio.mjs, with tests in runner/test/installer.test.mjs. Change the source, regenerate, and check that an existing project's text outside the Desk Studio markers stays intact.