WEFT_OS/.agents
Marco Allegretti 1e344d684d
docs: name the portable CI job in the verification runner
The portable profile mirrors the CI job that now runs on Ubuntu only
under the name portable.
2026-10-09 08:56:50 +00:00
..
agents docs: add engineering contract, contributor toolkit and templates 2026-10-09 08:34:48 +00:00
commands docs: add engineering contract, contributor toolkit and templates 2026-10-09 08:34:48 +00:00
scripts docs: name the portable CI job in the verification runner 2026-10-09 08:56:50 +00:00
skills docs: add engineering contract, contributor toolkit and templates 2026-10-09 08:34:48 +00:00
README.md docs: stop runner toolchain installs and widen maintenance form 2026-10-09 08:34:48 +00:00

WEFT OS contributor toolkit

Procedures, review roles, area knowledge and a verification runner for contributors. AGENTS.md is the engineering contract; BLUEPRINT.md is the accepted product direction; CONTRIBUTING.md is the maintainer-facing summary.

These files help apply the contract. They do not grant permissions, approve decisions, schedule work or change the working mode. If a guide here seems to disagree with AGENTS.md, the contract wins and the guide needs fixing.

Start

  1. Read AGENTS.md, identify the accepted scope and the owning component.
  2. Load only the skills that match the boundary you are changing.
  3. Use scope for an unverified report or proposal, and implement for accepted, verifiable work.
  4. Select checks and evidence with verify, then have the reviewer inspect the actual diff.

Commands

Commands are portable Markdown procedures. Follow them as checklists.

Command Input Result
scope Report, defect or proposal Evidence-backed issue draft with owner, acceptance criterion and proof
implement Issue or accepted scope Reviewed atomic change on a descriptive branch
verify Scope or diff Coverage map and actual check results
maintenance One named maintenance role One justified issue, or one isolated reviewed change
release Milestone scope and candidate commit Candidate evidence and a promotion recommendation

Roles

Roles are checklists for a reviewer or a focused pass over the code. A role file does nothing until a task invokes it.

Role Responsibility
reviewer Review a specified diff for correctness, scope, ownership and evidence without editing it
architecture-debt-scout Report the strongest present ownership or boundary problem; never edit repository files
continuous-simplicity Remove one duplicated decision, unnecessary state or misleading fallback path
continuous-refactoring Resolve one structural problem while preserving behavior, ownership and proof

Skills

Each skill is a SKILL.md with name and description metadata. The weft- prefix keeps them distinct from skills installed by other projects.

Skill Load when changing
weft-compositor-input Smithay compositor, Wayland protocols, surfaces, focus, geometry, input, DRM or winit backends
weft-servo-rendering Servo embedding, painting and presentation, the Servo fork and Stylo overrides, system UI and app pages
weft-runtime-capabilities Wasmtime host, WIT, WASI preopens, host imports, grants, file portal, seccomp
weft-appd-sessions Session lifecycle, readiness, child supervision, cleanup, appd IPC, WebSocket bridge
weft-packages-data Manifests, weft-pack, signing and trust, installation, updates, app data, EROFS images
weft-linux-deployment Nix flake and VM, systemd units, native dependencies, installed paths and endpoints
weft-integration-verification End-to-end fixtures, pixels and input, failure injection, reliability and evidence records
weft-documentation Public documentation, the blueprint, this toolkit, templates and the runner

Verification runner

scripts/verify.py runs the repository's actual check profiles. It needs Python 3.10 or newer. It works from any directory, runs fixed argument arrays from the repository root without a shell, stops at the first failure and returns its status. It never formats files, installs packages or toolchain targets, regenerates expectations, signs packages, commits or publishes. It sets RUSTUP_AUTO_INSTALL=0, so a missing pinned toolchain or component fails the check instead of being downloaded; install it with rustup show or rustup component add.

python .agents/scripts/verify.py --help
python .agents/scripts/verify.py portable linux --dry-run
python .agents/scripts/verify.py portable linux
Profile Runs Prerequisites
toolkit Link, anchor, metadata, catalog and issue-form checks; runner tests pip install -r .agents/scripts/requirements.txt
portable cargo fmt --check; Clippy and tests for crates built on every host Pinned toolchain
linux Clippy and tests for weft-compositor and the feature-disabled shells Linux Wayland, input, DRM and systemd development libraries
servo-embed cargo check of both Servo hosts with the real renderer feature As linux, plus the Servo build dependencies; long first build
runtime Clippy and tests for weft-runtime with wasmtime-runtime,net-fetch Pinned toolchain
demos cargo check of the demo components for wasm32-wasip2 rustup target add wasm32-wasip2
packages weft-pack check and weft-pack verify of the demo packages Pinned toolchain

All Cargo commands use --locked. Local [patch] overrides used for cross-repository development change the resolved graph and make locked checks fail; run the runner without them for evidence about the committed graph.

The runner covers compilation, lints, unit tests and package checks. It does not run a compositor, render pixels, launch a session, boot the VM or exercise a real component's host imports. Select that evidence with verify. Profiles are not a replacement for CI, and a passing profile is not approval to publish, merge or release. No hooks are installed by this toolkit; if you call the runner from a local hook, configure it in your own client or Git setup.

Maintaining the toolkit

Put area knowledge in a skill, repeatable steps in a command, review criteria in a role and executable checks in scripts/. Link to the contract and to the owning source instead of restating policy or freezing implementation status. List every command, role and skill in its table above; toolkit fails when a document is not linked from this catalog. Changes to the runner need a test showing failure behavior.

check_toolkit.py parses CommonMark links, images and reference links in this directory and in the top-level contributor documents. It ignores code spans, code blocks and HTML comments. It checks that local targets exist inside the repository, that #fragment links into Markdown files match a GitHub-style heading anchor, that metadata is a YAML mapping with unique string name and description fields and a name matching its path, and that issue forms parse. External URLs, raw HTML and the truth of the instructions still need review.

The structure follows the Resina Design System contributor toolkit at revision 1e768064f57a1e403ab271822383e732795905a6. WEFT's contract, ownership and evidence requirements determine its contents.