Contributing

Contributing

PRs welcome. Repo: https://github.com/mtecnic/clusterspace. Issues at https://github.com/mtecnic/clusterspace/issues.

---

Dev setup

git clone https://github.com/mtecnic/clusterspace.git
cd clusterspace
npm install
npm run rebuild    # native modules
npm run dev        # Vite + Electron, watches src/

See Installation for prerequisites and OS-specific build toolchain notes.

---

Branching model

• Default branch: main. PRs target main.
• No develop branch — main is the release line.
• Feature branches typically named feat/<short-description> or fix/<short-description>.
• Squash-merge is fine; merge commits are fine; rebase-merge is fine. Maintainer chooses based on the change size.

---

Code style

• TypeScript for everything in src/. Strict mode is on.
• 2-space indent, no semicolons-required (we use them most places but the linter is forgiving).
• No emojis in code or commits unless the user is explicitly using them.
• Match the surrounding style — when in doubt, look at adjacent files.
• No comments that just describe what the code does — well-named identifiers do that. Comments should explain why something non-obvious is there (a workaround, an invariant, a hidden constraint).

Pre-PR checks:

npx tsc --noEmit     # must be clean (unused-import warnings ok)
npm run build        # must succeed

(There's no full test suite yet — roadmap item. Manual testing is expected.)

---

Commit messages

Follow the conventional-commits-ish format the repo already uses:

feat(area): short imperative summary

Longer body explaining what and why.

Co-Authored-By: ...  (if pair-coding)

Common prefixes: feat, fix, docs, refactor, chore, wiki.

Look at git log --oneline for examples — there are many.

---

What needs a PR vs. an issue

Open an issue when	Open a PR when
You found a bug but don't have a fix	You have a fix
You want a feature but aren't sure of the design	You have a working impl + happy to discuss
The change touches the architecture or app contract	You're adding/modifying a tool, persona, etc.
You're not sure if it's wanted	You're confident it's an improvement

---

Files you'll most likely touch

If you're adding…	Look at
A new AI tool	Tool-Registry · AI-Tools-Reference · src/main/ai-tools/
A new IPC channel	IPC-Channels-Reference · src/shared/types.ts · src/preload/index.ts
A new dialog or UI surface	src/renderer/components/
A keyboard shortcut	src/renderer/hooks/useKeyboardShortcuts.ts
A new electron-store file	src/main/<your-area>-store.ts (look at existing stores for the pattern)
Goal runner behavior	Goal-Runner-Internals · src/main/goal-runner.ts
Personas / skills / task templates	resources/defaults/ (also user can override via [[Settings-and-Configuration

---

Testing locally

There's no test suite (yet). Manual smoke checks before PR:

1. npx tsc --noEmit — clean
2. npm run build — succeeds
3. npm run dev — app launches, panes work
4. Exercise the area you changed:
   • For AI tools: open chat panel, ask the AI to use the tool
   • For IPC: open DevTools, check the renderer-side window.electronAPI.<name>(...) call works
   • For UI: click around, verify no console errors
5. npm run dist — only if your change touches packaging (electron-builder.yml, package.json scripts, native modules)

---

Architecture do's and don'ts

Do

• Use electron-store for any new persistent state — match the pattern of existing stores
• Add new shared types to src/shared/types.ts, not in main- or renderer-specific files
• Use safeStorage for any secret material (API keys, passwords, tokens)
• Use the registry pattern for new AI tools — don't hardcode a giant switch
• Pass BrowserWindow and stores into constructors; don't reach for globals

Don't

• Don't import from src/main/ in renderer code (use IPC)
• Don't import from src/renderer/ in main code
• Don't introduce new direct ipcRenderer.invoke calls in renderer — go through the preload bridge
• Don't add console.logs without a reason — remove debug logs before merging
• Don't add files for "future use" — YAGNI

---

Documentation expectations

PRs that add user-facing features should also:

1. Update the Home navigation if the feature is large
2. Add a new wiki page (or update existing) for the feature — see how existing pages are structured
3. Update the Changelog entry
4. Update the Keyboard-Shortcuts table if applicable

Don't worry about updating every page that mentions the feature — links auto-resolve as the wiki grows.

---

Maintainer expectations

If you're a maintainer:

• Be welcoming. New contributors deserve patience.
• Code review focuses on: correctness, architecture fit, code style, not nitpicks about taste.
• Ship small. Big PRs are hard to review; suggest splitting when reasonable.
• Don't block on perfection. "Good enough to ship, iterate later" beats "stuck in review."

---

Roadmap items good for first contributions

Issue	Why it's good for first-time
Adding light theme	Self-contained, visible result, no architectural risk
Adding new persona / skill / task template defaults	No code change needed beyond a markdown file
Adding wiki content	The wiki is its own repo; PR there
Migrating remaining IPC channels off string literals into IPC_CHANNELS	Mechanical, type-safe wins
Authoring a new plugin tool in <userData>/.../config/tools/	Doesn't even need a fork

See the Roadmap for more.

---

See also

• Architecture-Overview — codebase structure
• IPC-Channels-Reference — adding new channels
• Tool-Registry — adding new tools
• Installation — getting set up