Contributing

Getting Started

HQ is split across several repos (see the Ecosystem & Repo Map). Contribute to the repo that owns the surface you’re changing: indigoai-us/hq-cli for the CLI, indigoai-us/hq-cloud for the sync engine, indigoai-us/create-hq for the installer, indigoai-us/hq-desktop-app for the desktop app. Scaffold changes go to indigoai-us/hq-core-staging, not hq-core.

1. Fork the target repo: gh repo fork indigoai-us/hq-cli (or another repo)
2. Clone your fork and cd into it
3. Install dependencies: pnpm install (hq-cli, hq-cloud, hq-desktop-app, hq-console, hq-pro) or npm ci (create-hq, hq-deploy, indigo-docs)
4. Build: pnpm run build (or npm run build)
5. Create a branch: git checkout -b feature/my-feature

Branch Strategy

Branch	Purpose
main	Production. Always deployable.
feature/*	New features. Branch from main.
fix/*	Bug fixes. Branch from main.
docs/*	Documentation changes.

Making Changes

Code changes

1. Make changes inside the repo that owns the surface (e.g. hq-cli, hq-cloud)
2. Build it: pnpm run build
3. Run typecheck: pnpm run typecheck
4. Test your changes locally (see the Testing guide)
5. For a user-facing change in hq-cli or hq-cloud, add a release-note fragment at changelog.d/<branch-slug>.md instead of editing CHANGELOG.md. Changes with no user impact get the no-changelog PR label.
6. Commit with a clear, descriptive message

Scaffold changes (hq-core)

1. Open the PR against main in indigoai-us/hq-core-staging
2. Test in a throwaway instance: npx create-hq ~/test-hq --local-template <path-to-your-staging-checkout>
3. After merge, the change ships in the next hq-core release, cut by the promote-to-hq-core workflow (see Publishing Packages)

Documentation changes (this site)

1. Edit MDX files in indigo-docs under src/content/docs/
2. Preview locally: npm run dev
3. Verify at http://localhost:4321

Commit Messages

Follow conventional commits:

feat: add new worker scaffold command
fix: correct journal hash on Windows
docs: update cloud sync architecture page
chore: bump dependencies

Format: type: short description

Types: feat, fix, docs, chore, refactor, test, style

Pull Requests

Creating a PR

git push origin feature/my-feature
gh pr create --title "feat: my feature" --body "Description of changes"

PR Checklist

• Code builds without errors (pnpm run build or npm run build)
• TypeScript passes (pnpm run typecheck or npm run typecheck)
• Release-note fragment added in changelog.d/, or no-changelog label applied (hq-cli, hq-cloud)
• Tests pass (if applicable)
• No secrets or PII in committed files
• Documentation updated if needed
• Commit messages follow conventional format

Review Process

1. Open PR against main
2. CI runs automatically
3. Core team reviews
4. Address feedback
5. Squash merge when approved

Code Style

• TypeScript for all packages
• ES Modules (type: “module” in package.json)
• Strict mode enabled in tsconfig
• No default exports — use named exports
• Prefer async/await over raw promises
• Use interface over type for object shapes
• Error handling: throw typed errors, catch at boundaries

Architecture Decisions

When proposing significant changes:

1. Open an issue describing the problem and proposed solution
2. Get feedback before implementing
3. Document architectural decisions in PR description
4. Update relevant docs pages

Areas for Contribution

Area	Examples
Module sync strategies	A distinct copy strategy (it currently runs the merge implementation)
CLI commands	New module management features
Testing	Unit tests, integration tests, E2E
Documentation	Tutorials, examples, API reference improvements
Scaffold content (hq-core-staging)	New workers, knowledge bases, skills

Questions?

• Open a GitHub issue for bugs and feature requests
• Check the docs site for architecture and usage guides
• Review existing PRs for code patterns and conventions