the-nexus/CONTRIBUTING.md

Contributing to The Nexus

Thanks for contributing to Timmy's sovereign home. Please read this before opening a PR.

Project Stack

• Vanilla JS ES modules, Three.js 0.183, no bundler
• Static files — no build step
• Import maps in index.html handle Three.js resolution

Architecture

index.html    # Entry point: HUD, chat panel, loading screen
style.css     # Design system: dark space theme, holographic panels
app.js        # Three.js scene, shaders, controls, game loop (~all logic)

Keep logic in app.js. Don't split without a good reason.

Conventions

• ES modules only — no CommonJS, no bundler imports
• Color palette — defined in NEXUS.colors at the top of app.js; use it, don't hardcode colors
• Conventional commits: feat:, fix:, refactor:, test:, chore:
• Branch naming: claude/issue-{N} for agent work, yourname/issue-{N} for humans
• One PR at a time — wait for the merge-bot before opening the next

Before You Submit

1. Run the JS syntax check:

   node --check app.js
   

2. Validate index.html — it must be valid HTML
3. Keep JS files under 500 KB
4. Any .json files you add must parse cleanly

These are the same checks the merge-bot runs. Failing them will block your PR.

Running Locally

npx serve . -l 3000
# open http://localhost:3000

PR Rules

• Base your branch on latest main
• Squash merge only
• Do not merge manually — the merge-bot handles merges
• If merge-bot comments "CONFLICT": rebase onto main and force-push your branch
• Include Fixes #N or Refs #N in your commit message

Issue Ordering

The Nexus v1 issues are sequential — each builds on the last. Check the build order in CLAUDE.md before starting work to avoid conflicts.

Questions

Open an issue or reach out via the Timmy Terminal chat inside the Nexus.