Contributing

The framework repository does not contain a CONTRIBUTING file. This page summarizes the maintainer rules the repository actually documents, mainly in the maintainer guide and the packaging contract.

Where changes go

You want to change	Edit	Never edit
A rule, workflow, policy, profile, or template	src/kiyo/... (the canonical source)	Generated copies under dist/
Host metadata or activation guidance	platforms/<host>/	Canonical frontmatter (name and description only)
Package contents (added or removed files)	tools/packaging-inputs.json, deliberately	The builder’s allowlist checks
Documentation or evidence	docs/... with dated, scoped statements	Historical evidence records, which are kept

Rules that keep the framework coherent

1. One source. Do not fix a rule by editing one generated copy. Regenerate instead.
2. Exactly eight Skills. Do not turn a submode, such as Security’s skills or Memory’s sync, into a ninth Skill.
3. No unsupported native fields. Do not add invented permission or “core” fields to closed host schemas. Access contracts stay in Markdown.
4. Stable control IDs. Never renumber or reuse an ID. A materially different obligation needs a new ID and migration history.
5. Budgets hold. KIYO.md plus the bootstrap stays within 120 lines and 600 words; each SKILL.md within 250 lines and 1,200 words.
6. Neutral templates. No project facts, personal paths, or credentials in shipped templates. The static tests scan for them.
7. No runtime. No hooks, MCP servers, scripts, or executables in packages.
8. Honest evidence. Commands in docs are templates, not execution records, unless they actually ran. Keep static, behavioral, and live evidence separate. Missing required evidence cannot be relabeled optional.

Build and check a change

From the framework repository root (command templates)

python -B tools/package_distributions.py --output <fresh-archive-directory> --inventory <fresh-inventory.json>
python -B tests/packaging/test_distributions.py --report <fresh-packaging-results.json>
python -B tests/static/test_contracts.py --report <fresh-static-results.json> --inventory <fresh-inventory.json> --archives <fresh-archive-directory>
python -B tests/behavioral/evaluation/test_suite.py --report <fresh-offline-helper-results.json>

• Build twice from identical bytes and compare inventories and archives.
• Extract to fresh paths, including paths with spaces, and verify contained exact-case resources and all eight Skills.
• Existing builders refuse changed pre-existing outputs. Use fresh destinations and keep prior evidence.
• The static suite’s default inventory is stale after the rename; see Testing strategy.

Release boundary

No command commits, tags, pushes, submits, or publishes. Public release needs real owner decisions on identity, version, license, publisher, and destination (DEC-001 to DEC-003), plus the owner-required tests. Critical unsafe behavior, secret exposure, or fabricated check results block release. See Status and releases.

Reporting problems

Use the issue report checklist: target, versions, source, exact sanitized error, selected Skill, expected versus observed behavior. Never include credentials or raw private logs.