WEFT_OS/.agents/skills/weft-documentation/SKILL.md

54 lines
2.5 KiB
Markdown
Raw Normal View History

docs: add engineering contract, contributor toolkit and templates Add AGENTS.md as the single engineering contract: sources of truth, evidence and proof requirements, ownership, working modes, the reviewed change loop, maintenance isolation, decision authority, dependency and fork rules, the 0.0.x to 0.1.0 release progression, and branch and publication rules. Add .agents/ with scope, implement, verify, maintenance and release procedures; reviewer, architecture debt scout, simplicity and refactoring roles; skills for the compositor, Servo rendering, runtime capabilities, appd sessions, packages and data, Linux deployment, integration verification and documentation; and verify.py, which runs the existing check profiles with --locked from any directory, stops on the first failure and supports --dry-run. check_toolkit.py validates local links and heading anchors, metadata, catalog coverage and issue forms. A new contributor-toolkit CI job runs both. The structure follows the Resina Design System toolkit at 1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT. Validation, against the committed lockfiles: - verify.py toolkit: checker passes, 28 runner/checker tests pass - verify.py portable, demos, packages: pass - verify.py linux, runtime, servo-embed: fail on existing defects (clippy collapsible_if in the winit backend, three clippy lints in weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo revision's servo-layout); the runner reports the failing status Add CONTRIBUTING.md, issue forms for defects and changes, maintenance problems and decisions of direction, and a pull request template asking for ownership, proof and the validation actually performed. README.md links the contribution guide.
2026-10-08 23:40:08 +00:00
---
name: weft-documentation
description: Use for WEFT OS public documentation, the blueprint, this contributor toolkit, issue and pull request templates and the verification runner.
---
# Documentation and the toolkit
[AGENTS.md](../../../AGENTS.md) is the only policy source. The
[blueprint](../../../BLUEPRINT.md) holds accepted direction. Public documentation
in [README.md](../../../README.md) and [docs/](../../../docs/architecture.md)
describes implemented behavior and must agree with source.
## Working rules
- Verify every command, path, feature, environment variable and API you document
against the current source, and run commands where practical. Keep blueprint
intent, implemented behavior and executed evidence distinct: "implemented",
"verified" and "planned" are different claims.
- Correct documentation that contradicts source instead of working around it;
for example, a pin file that disagrees with `Cargo.lock`, or a signing
description that differs from the implemented inventory.
- Link durable decisions and requirements to their owning artifact. Toolkit files
provide procedures and area knowledge, never a second policy, permissions,
schedules or an internal log.
- Write issues, pull requests, commits and release notes for maintainers: the
problem, the resulting behavior and the evidence. No attribution, trailers,
prompts or process narration.
- Keep Markdown portable: standard CommonMark links and tables, YAML front matter
with `name` and `description` only, no client-specific syntax required to
follow a procedure.
## Toolkit changes
Add area knowledge in a skill, repeatable steps in a command, review criteria in
a role and executable checks in `.agents/scripts/`. Update the
[catalog](../../README.md) for every new document. Then run:
```sh
pip install -r .agents/scripts/requirements.txt
python .agents/scripts/verify.py toolkit
```
That checks links, anchors, metadata, catalog coverage and issue forms, and runs
the runner tests. For runner changes, add tests for failure propagation,
unknown input, missing executables and execution from another directory. Review
the instructions manually against `AGENTS.md`, the blueprint and CI; passing
checks does not establish that the instructions are true.
Changes to the blueprint or contract are governance changes: follow the
[reviewed loop](../../../AGENTS.md#5-reviewed-change-loop), check every document
that links to the changed sections, and seek a
[decision](../../../AGENTS.md#9-decisions-and-authority) for a material change of
direction.