Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
51 lines (35 loc) · 2.82 KB

CONTRIBUTING.md

File metadata and controls

51 lines (35 loc) · 2.82 KB

Contributing to Djinn

An @enchanter-ai product.

Thanks for your interest in contributing. This document captures the conventions every sibling in the enchanter-ai ecosystem follows. Read CLAUDE.md before opening your first PR — it's the binding behavioral contract for the plugin.

Ground rules

  1. Zero external runtime deps. Hooks: bash + jq only. Scripts: Python 3.8+ stdlib only. If you need a new dep, open an issue first — the bar for adding one is high.
  2. Named algorithms. Every engine has an ID (e.g. D1) and an academic-style name in the [Method] [Domain] [Action] pattern. Derivations live in docs/science/README.md.
  3. Managed agent tiers. Opus orchestrates / judges. Sonnet executes loops. Haiku validates shape. Never route a Haiku task to Opus.
  4. Emu-style marketplace. Each sub-plugin ships .claude-plugin/plugin.json + {agents,commands,hooks,skills,state}/ + README.md.
  5. Diagrams from source-of-truth. docs/architecture/*.mmd + index.html are regenerated by docs/architecture/generate.py. Do not hand-edit.

Dev setup

git clone https://github.com/enchanter-ai/djinn
cd djinn
bash install.sh                                  # pre-flight checks, clone to ~/.claude/plugins/
cd docs/assets && npm install                    # renderer toolchain (mmdc + puppeteer + mathjax)
cd ../../ && bash tests/run-all.sh               # smoke tests

Before opening a PR

  1. Run the generator. python docs/architecture/generate.py — regenerates the four .mmd diagrams + index.html. Commit the result.
  2. Run the tests. bash tests/run-all.sh — every sub-plugin's tests/ dir must return zero.
  3. Verify the conduct modules are current. shared/vis/conduct/*.md are the universal behavioral contract. Compare against upstream (enchanter-ai/wixie); if they've drifted, rebase before proceeding.
  4. Check the brand standard. Every engine named. Every agent tiered. No sibling-identifier leaks. No hand-edited diagrams.

Commit conventions

Conventional Commits. Scope by sub-plugin slug:

feat(intent-anchor): add refresh-delta labeling for side-quest vs refocus
fix(drift-aligner): handle empty reservoir on PreCompact without crashing
docs(shared): update conduct/precedent.md with new failure code
refactor(docs): move diagram config into mermaid.config.json

Scopes: sub-plugin slug (intent-anchor, ...), shared, docs, tests, or repo for top-level.

Reporting issues

Open at https://github.com/enchanter-ai/djinn/issues. Include: plugin version (from .claude-plugin/marketplace.json#metadata.version), Claude Code version, repro steps, expected vs. actual.

Code of conduct

Be kind. Debate ideas, not people. The @enchanter-ai ecosystem is built on mutual trust that each sibling respects the others' contracts and event-bus boundaries.
⚡