Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
These guidelines define the standards and processes for contributing to the Jarvis-Glas project. The project is a multi-layered desktop AI assistant framework consisting of an Electron frontend, a TypeScript/Bun backend, and specialized components like Handtracking (Barehands) and specialized installers. Contributors must adhere to specific architectural boundaries, design tokens, and state management principles to ensure system integrity and visual consistency.
Sources: CONTRIBUTING.md:41-46, instructions/AGENTS.md:11-18
Project Architecture & Tech Stack
The project is divided into distinct technical layers. Contributors should ensure that changes are made in the appropriate directory and use the sanctioned technology for that component.
| Component | Path | Technology | Authority |
|---|---|---|---|
| Desktop App | src/ | Electron + React + Three.js | Presentation & UI State |
| Backend Service | backend/ | Bun + TypeScript | Work: sessions, tools, models |
| Handtracking | backend/src/barehands/ | Python (Port 8794) | Input processing |
| Bootstrap Installer | apps/bootstrap-installer/ | Tauri + Rust + PowerShell | System setup |
| Shared Logic | packages/shared/ | TypeScript | Shared Types & Helpers |
Sources: CONTRIBUTING.md:41-46, instructions/AGENTS.md:13-17, instructions/GEMINI.md:6-14
Architectural Separation
A core principle is the "Clean Seams" rule. The renderer must never reach for Node or Electron directly; native power is accessed only through deliberate, typed capability bridges. State must be placed with its authority: the backend owns shared truth, Electron owns machine facts, and the renderer owns presentation-only ephemeral state.
Sources: instructions/AGENTS.md:18-29
Development Workflow
Contributors must follow the established Git and build workflows to maintain project stability.
Quick Start
# 1. Fork + Clone
git clone https://github.com/%3Cyour-user%3E/jarvis-desktop_glas.git
cd jarvis-desktop_glas
# 2. Install dependencies
bun install
# 3. Create a branch
git checkout -b feature/<description>
# 4. Build and Test
bun run build
bun run check
Sources: CONTRIBUTING.md:5-24, instructions/GEMINI.md:16-17
Contribution Lifecycle
The following diagram illustrates the workflow from issue creation to pull request approval.
Brief explanation: The process starts with issue documentation, followed by local development and rigorous verification before a Pull Request is submitted for review.
Sources: CONTRIBUTING.md:28-40, instructions/GEMINI.md:16-21
Commit & PR Standards
- Commit Format:
type(scope): description(Types:feat,fix,docs,refactor,test,chore). - Secrets: Never commit API keys;
.envfiles are ignored. - PR Checklist: Must link an issue (
Closes #123), run local builds, include CHANGELOG entries for user-visible changes, and contain no secrets.
Sources: CONTRIBUTING.md:33-40, instructions/CONTRIBUTING.md:48-53
Design & UI Guidelines
The "Desktop Design System" governs all visual contributions. The primary rule is: tokens over literals, flat over boxed.
Design Principles
- Flatness: No nested card-in-card or divider borders inside panels. Use whitespace and hairlines.
- One Primitive per Concern: Use existing components like
Button,SearchField,Loader, orErrorStateinstead of creating new ones. - Tokens only: Reference CSS variables (e.g.,
--ui-*,--shadow-nous) instead of hardcoded hex colors. - Intent before Automation: Do not automatically open panes or steal focus; surface actions for the user to decide.
Sources: instructions/DESIGN.md:1-55
Visual Tokens
Contributors must use the following core tokens defined in the design system.
| Category | Key Tokens | Usage |
|---|---|---|
| Strokes | --ui-stroke-tertiary | Default in-panel dividers |
| Overlays | --stroke-nous + --shadow-nous | Floating panels and dialogs |
| Text | --ui-text-primary/secondary/tertiary | Text hierarchy |
| Brand | --theme-primary, --ui-accent | Branding elements |
| Elevation | --z-modal, --z-connecting, --z-crash | Fixed z-index ladder |
Sources: instructions/DESIGN.md:58-75, instructions/DESIGN.md:200-215
Engineering & State Guidelines
Contributing to the core logic requires understanding the "Judgment Guide" for desktop engineering.
State Management
- Nano-stores: Shared state uses small
nanostoresinstead of prop-drilling. - Authority-based state: State must live where it is authoritative. Persisted state must be scoped (e.g., global, profile-specific, or session-specific).
- Optimistic UI: Direct manipulation should update the view first, with disk/network persistence reconciling afterward.
Sources: instructions/DESIGN.md:280-295, instructions/AGENTS.md:21-45
The Observable Ladder
Discovery and resolution logic (like backend discovery or auth) must follow an ordered ladder of candidates. A candidate is only trusted after validation at the boundary. Failed reads should fall to the next rung, while failed authoritative writes should rollback and surface an error.
Sources: instructions/AGENTS.md:85-110
Identity & Tone (The Soul)
Changes to the AI assistant's persona or communication must align with the SOUL.md directives.
Brief explanation: Jarvis follows a "Maximum Intelligence, Minimum Interruption" principle, favoring silent execution and technical HUD feedback over verbal small talk.
Sources: SOUL.md:1-35, SOUL.md:130-145
Personality Rules
- Anrede: Always use "Master" (in German: "Master").
- Language: Default to German unless code or specific technical terms require English.
- Communication Style: Brief, technical, precise, and un-intrusive. No chatbot phrases like "I hope that helps."
- Privacy: Hard-mute by default (
muted: true); respect the person using it.
Sources: SOUL.md:40-60, SOUL.md:165-175, instructions/AGENTS.md:128-140
Testing & Validation
Testing is a "habit of proof." Contributors must test behaviors that would break a user rather than today's data snapshots.
- Run Checks:
bun run check(runs typecheck and tests). - Verification: Changes must pass the
DESIGN.mdchecklist and the engineering taste test before hand-off. - Memory Updates: Agents or developers should log relevant changes in
.agent/CONVERSATION_MEMORY.md(if applicable).
Sources: package.json:11-13, instructions/AGENTS.md:143-160, instructions/GEMINI.md:16-21