Contributing

Getting Started

HQ is split across several repos (see the Ecosystem & Repo Map). Contribute to the specific repo that owns the surface you’re changing — e.g. indigoai-us/hq-cli for the CLI, indigoai-us/hq-core for the scaffold, indigoai-us/hq-cloud for the sync engine.

1. Fork the target repo: gh repo fork indigoai-us/hq-cli (or hq-core, hq-cloud, …)
2. Clone your fork and cd into it
3. Install dependencies: npm ci (or pnpm install for hq-console / hq-pro)
4. Build: 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: npm run build
3. Run typecheck: npm run typecheck
4. Test your changes locally (see Testing guide)
5. Commit with a clear, descriptive message

Scaffold changes (hq-core)

1. Edit the scaffold seed in the hq-core repo
2. Test by scaffolding a throwaway instance: npx create-hq ~/test-hq
3. Verify the change works in a fresh HQ instance

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 (npm run build)
• TypeScript passes (npm run typecheck)
• 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 (build + typecheck)
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
New sync strategies	Copy strategy, two-way merge
PWA features	Offline mode, push notifications, Monaco editor
CLI commands	New module management features
Testing	Unit tests, integration tests, E2E
Documentation	Tutorials, examples, API reference improvements
Template content	New workers, knowledge bases, commands

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