Contributing to Moguri
How to report issues, propose changes and get a pull request merged.
Published unchanged from CONTRIBUTING.md in Moguri's source repository at commit b686ddc (0.32.0-alpha.1). That repository isn't public yet, so references to files that only exist there appear as plain text with a dotted underline.
Thanks for helping build Moguri. Bug reports, documentation fixes, tests and code are all welcome. This guide explains how to propose a change and get it merged.
Before you start
- Follow the Code of Conduct in every project space.
- Security issues: do not open a public issue. Follow SECURITY.md.
- Read the AI policy (not public yet): you are responsible for everything you submit, however it was produced.
- Coding agents: read AGENTS.md (not public yet) before editing anything. It holds the repository's binding architecture rules and verified commands.
Issues and proposals
- Search existing issues (not public yet) first. The roadmap lives in remaining milestone gaps and its parent issue, #39 (not public yet).
- Bugs: include the Moguri version, your macOS version, the client (TUI, desktop, CLI or SDK), the environment (Local, Sandbox or Remote), what you expected, and the smallest steps that reproduce it. Use generated data; never paste credentials, tokens or private repository content.
- Features and larger changes: open an issue describing the problem and your proposed approach before writing a large patch. Moguri works in a documented phase order, so some ideas wait for earlier milestones.
Development setup
You need macOS on Apple silicon for the full suite, and Node.js 26 from
.node-version (not public yet).
npm ci
npm run build
npm start -- --project /absolute/path/to/project # TUI
npm run desktop # desktop app
The development guide covers the code layout, every check and debugging. Releasing covers the release process, which only maintainers run.
Making a change
Create a branch from
mainand keep the change focused on one problem.Change the service, SDK and clients together where needed. TUI, desktop and CLI share one SDK and must not keep client-only state.
Add or update tests that would fail without your change. Use generated fixtures only: no real credentials, customer data or personal data.
Update the relevant documentation under
docs/in the same change. Keep the README short.Run the checks locally. CI runs only after merging to
main, not on pull requests:npm run typecheck npm run build node --import tsx --test tests/<affected>.test.ts # focused suites first npm test # full suite npm run test:e2e # when the desktop changes npm audit --audit-level=moderateWrite commit messages as short imperative sentences that say what changed, for example
Add retry backoff to model recovery.
Pull requests
- Describe what changed and why, link the issue, and list the checks you ran with their results.
- Call out schema or protocol changes, migrations, new dependencies and their licenses (third-party components), and any accessibility impact (ACCESSIBILITY.md).
- A maintainer reviews every pull request. Address feedback with new commits, and reply to each review thread so reviewers can follow the discussion.
By contributing, you agree that your contribution is licensed under the project's MIT License.