Contributing

Contributing

This page summarizes the contribution workflow; the authoritative version is CONTRIBUTING.md in the repo. A change here fans out to all nine OS repos, so the bar is: is this truly Core, and is it healthy?

Is it actually Core?

Add it here only if it is identical on every machine (not OS-specific) and not offensive/engagement tooling. Otherwise:

If it changes when…	It belongs in…
the operating system changes (pkg mgr, paths, clipboard)	the OS repo
you as an operator change (C2, wordlists, engagement layout)	dotfiles-Kali
neither — it's the same everywhere	here

See Architecture & the Three-Layer Model for the reasoning.

Adding a new Core file (checklist)

1. Confirm it's Core (the table above).
2. Drop it into the matching path.
3. Strip out anything OS-specific (clipboard, paths, package manager).
4. Add the path to core.manifest — the audit enforces this in both directions.
5. Wire the symlink into each OS repo's bootstrap.sh if it needs one.
6. ./scripts/audit-core.sh — green before you push.
7. ./scripts/sync-core.sh to vendor it into every OS repo.

Run the audit before you push

scripts/audit-core.sh is the single gate (the same one CI and pre-commit run):

./scripts/audit-core.sh           # full run
./scripts/audit-core.sh --quiet   # only skips/failures + summary
make audit-changed                # only what your diff touches

See The Audit (Quality Gate) for what it checks.

Pre-commit (recommended)

pip install pre-commit && pre-commit install
pre-commit run --all-files

Conventions

• Executable bits matter. Anything invoked by path (bin/ shims, scripts/ tooling, tmux/scripts/ popups, the maint runner) must be +x; the sourced zsh/*.zsh modules must stay non-executable. The audit asserts both.
• Indentation is 2-space across the tree (.editorconfig).
• Keep OS-specific bits out — strip clipboard/paths/package-manager logic into the OS repo.

Commit messages

Use a Conventional Commits prefix so the log reads as a changelog:

type(scope): short imperative summary

optional body explaining the why

Common types: fix, feat, test, ci, docs, chore, perf. The scope is the Core area touched (zsh, nvim, tmux, audit, …). A user-visible change should land in CHANGELOG.md under [Unreleased] in the same commit.

See also

• The Audit (Quality Gate)
• Consuming Core in an OS Repo
• FAQ & Troubleshooting