Smoke test required

...

← All documentation

Documentation

Contributing

**Status:** active · last reviewed 2026-05-03

source: CONTRIBUTING.md

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>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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"
  • AI-pair-programmed commits include a Co-Authored-By trailer
  • 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 claude/<topic> (per CLAUDE.md global policy). Examples: claude/living-things-runtime, claude/mobile-responsive-sweep.
  • Warp branches — claude/warp-<stamp>-<slot> (auto-created by bin/warp_split_spawn.sh).
  • PR target — always main. Squash-merge preferred to keep history readable.

Warp protocol

Endenza uses a parallel-branch execution model called “warp” for larger tasks. The Maestro decomposes work into slices (slots a/b/c/…), fires each as an isolated Claude Code session on its own git worktree, and merges the results.

Overview: - Each slot gets a pre-created branch (claude/warp-<stamp>-<slot>) and a worktree at .claude/warp-worktrees/<stamp>/<slot>/. - Slots commit incrementally (one commit per acceptance criterion) so a SIGTERM loses at most one unfinished criterion. - Maestro runs bin/warp_post_merge_verify.sh after all slots merge and before pushing.

For full depth: docs/operations/WARP_PROTOCOL_AUDIT_2026-05-03.md

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:

Workflow Coverage
.github/workflows/integration-test.yml Bash parse + shellcheck, JSON validity, plugin + marketplace manifest schema, full pytest suite
.github/workflows/a11y-check.yml WCAG AA contrast audit + keyboard a11y verification

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:

Area Canonical
Operating contract for Agents plugins/endenza/templates/AGENT.md
Operating contract for Maestro plugins/endenza/templates/MAESTRO.md
Warp worker operating contract plugins/endenza/templates/WORKER.md
Product vision + terminology docs/grand-plan/MANIFESTO.md
Autopilot pipeline docs/architecture/AUTOPILOT_DESIGN.md
BYOK architecture docs/architecture/BYOK_ARCHITECTURE.md
Warp protocol audit docs/operations/WARP_PROTOCOL_AUDIT_2026-05-03.md

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 (claude-ensemble). The dashboard companion repo syncs from here:

  • KiwiMaddog2020/ensemble-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, brew, dashboard generate, BYOK, Cloudflare Tunnel, 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).