mirror of
https://github.com/marcoallegretti/WEFT_OS.git
synced 2026-11-22 08:13:59 +00:00
54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
|
|
---
|
||
|
|
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.
|