Contributing

Endenza is a personal project in private preview. Public contribution is not yet open - but if you find a bug, have a security concern, or want to suggest something, here is how.

TL;DR

• Bugs: open a GitHub issue using the bug template
• Security: see SECURITY.md (do not open public issues for vulnerabilities)
• Features / ideas: open a discussion or use the feature-request template
• Code: if you want to send a PR, read this file first

Code style

Python is linted with ruff (install via brew: brew install ruff). Shell is linted with shellcheck. Run both before committing:

ruff check .
bash -c 'set -e; for f in plugins/endenza/bin/*.sh bin/*.sh; do shellcheck "$f"; done; echo shellcheck OK'

No .prettierrc workarounds needed: the repo root .prettierrc and .editorconfig cover everything else. Match the existing style in whatever file you are touching.

Edit discipline

Every change follows the rule set baked into every Agent operating in this repo:

1. Touch only what the task requires. No drive-by refactors.
2. No dead code. No commented-out blocks. No orphan imports. No TODO: fix later.
3. Remove cleanly. Delete the code, update callers, verify nothing references it.
4. No narration comments. Only write a comment when the WHY is genuinely non-obvious and no identifier name can carry it.

Commit messages

Conventional commit format, always:

<type>(<scope>): <short description in imperative mood>

<body: explains WHY, not what; the diff shows what>

Types: feat, fix, docs, refactor, test, chore Scope: optional (terminal, dashboard, sprite, plugin, docs, warp, etc.)

• First line ≤ 72 characters
• Imperative mood: "Fix lock release race" not "Fixed lock release race"
• No [autopilot] prefix on human-authored commits: that prefix is reserved for machine-only audit

Branching

• main: protected. Merges only via PR or Maestro merge.
• Feature branches: named by owner and topic, for example feature/account-flow or codex/studio-polish.
• PR target: always main. Squash-merge preferred to keep history readable.

Testing

Run the relevant slice of the test suite before submitting:

# Full suite
python3 -m pytest tests/ -q

# Targeted (examples)
python3 -m pytest tests/ -k "terminal" -q
python3 -m pytest tests/ -k "brand" -q

# Lock-race smoke (plugin)
bash plugins/endenza/bin/test_lock_race.sh   # expect 10/10 rounds passed
bash plugins/endenza/bin/self_test.sh        # all green

CI runs via GitHub Actions on every PR + push to main:

If a job fails on main, escalate to Maestro: do not silently disable. Local pre-flight before pushing: python3 -m pytest tests/ -q && bash bin/dashboard-generate.sh.

Architecture references

If you are touching anything beyond docs, read the relevant canonical first:

When you change a rule, update the canonical. Never fork it.

What to avoid

• Don’t bypass the lock. Don’t write state.json.active_autopilot_chat or state.lock.d/ unless you have followed the acquire protocol.
• Don’t skip the prelude. Every scheduled task starts with routine_prelude.sh. Mode gates and work-hours respect live there.
• Don’t introduce a build step. The platform server is vanilla Python stdlib + no JS framework dep. Tempted? Stop and ask.
• Don’t commit secrets. .env.local is gitignored for a reason. Check SECURITY.md for the sensitivity class table.

Cross-repo work

Source-of-truth is this repo (endenza). The dashboard companion repo syncs from here:

• KiwiMaddog2020/endenza-dashboard: public dashboard (auto-generated 3× daily)

If your change affects a synced file, the sync is the responsibility of the same PR.

Setup

See docs/getting-started/INSTALL.md for the full install walkthrough (clone, dependencies, dashboard generation, BYOK, hosting, runner setup, and the menubar app).

Code of conduct

See CODE_OF_CONDUCT.md. The short version: be respectful, focus on the work.

License

By contributing, you agree your contribution is MIT-licensed (the project license).