Contributing to Hexabot (v3)

Thanks for your interest in contributing.

This guide is for the current v3 development line.

Branch and CI model

• main is the active v3 branch. Open pull requests against main.
• Pull requests targeting main trigger .github/workflows/main-ci.yml.
• The CI gate runs: pnpm typecheck, pnpm lint, pnpm test, pnpm build.

Security vulnerabilities

Do not open public GitHub issues for security vulnerabilities.

Report vulnerabilities privately to hello@hexabot.ai (see SECURITY.md) with:

• affected component/version,
• reproduction steps,
• impact,
• proposed mitigation (if available).

Development prerequisites

• Node.js ^24.17.0
• PNPM 11.8.0 (via Corepack)
• Git

From the repository root:

corepack enable pnpm@11.8.0
pnpm install

Monorepo architecture

Hexabot uses a PNPM workspace monorepo orchestrated by Turborepo.

Package	Responsibility
@hexabot-ai/api	NestJS backend, TypeORM entities/repositories/migrations, workflow runtime APIs
@hexabot-ai/frontend	React SPA admin app (Vite + React Router)
@hexabot-ai/widget	Embeddable live chat widget
@hexabot-ai/agentic	YAML DSL + typed workflow runtime
@hexabot-ai/graph	Reusable workflow graph editor/rendering package
@hexabot-ai/types	Shared Zod-first schemas/contracts
@hexabot-ai/cli	CLI for project bootstrap and operations

Package documentation

• CLI
• API
• Frontend
• Agentic
• Graph
• Types
• Widget

Contribution workflow

1. Sync and branch from main.

git checkout main
git pull
git checkout -b feat/short-description

2. Make focused changes.

• Avoid unrelated refactors.
• Keep pull requests small and reviewable.
• Update docs when behavior or contracts change.

3. Run relevant checks locally.

Package-scoped checks (recommended while iterating):

pnpm --filter <workspace-name> typecheck
pnpm --filter <workspace-name> lint
pnpm --filter <workspace-name> test
pnpm --filter <workspace-name> build

Full v3 gate before opening/updating a PR:

pnpm typecheck
pnpm lint
pnpm test
pnpm build

4. Commit using Conventional Commit style (commitlint is enforced).

Examples:

• fix(api): handle null tool bindings in workflow parser
• feat(frontend): add workflow run timeline widget
• docs: update v3 contribution guide

5. Open a pull request to main.

• Fill the PR template.
• Link related issues (for example: Fixes #123).
• Include test evidence and screenshots/logs when relevant.

Reporting bugs and requesting features

• Bugs: open a GitHub bug issue with clear reproduction steps and logs.
• Features: open a feature request issue, or discuss early on Discord before large changes.
• Questions/support: use Discord: https://discord.gg/rNb9t2MFkG

For Coding Agents (AI Contributors)

Read this section as an operational checklist.

1. Instruction precedence

• Read the closest AGENTS.md for every file you edit.
• Nearest AGENTS.md overrides broader instructions.
• For cross-package changes, follow root AGENTS.md plus each package-level AGENTS.md.

2. Package manager and dependency rules

• Use PNPM only for workspace work.
• Do not use npm install or yarn for monorepo dependency updates.
• Add dependencies from repo root with filters:
  • pnpm add <pkg> --filter <workspace-name>
  • pnpm add -D <pkg> --filter <workspace-name>
• Do not hand-edit pnpm-lock.yaml.

3. Change guardrails

• Keep diffs scoped to the task.
• Do not edit generated artifacts (dist/, coverage/, build output).
• Preserve required license headers in source files.
• Do not run release/version scripts unless explicitly requested.

4. Validation expectations

• Run typecheck, lint, test, and build for touched workspaces.
• For shared contracts or cross-package changes, run full workspace checks from root.

License and contribution terms

This section is a contributor summary, not legal advice. Always consult license files directly.

License map in this monorepo (v3/main)

Root workspace and all current workspace packages (api, frontend, widget, graph, agentic, types, cli) declare FCL-1.0-ALv2.

FCL-1.0-ALv2 (summary)

For components under FCL-1.0-ALv2:

• Future license: Apache-2.0 becomes available per version on the second anniversary of that version's availability.
• License-key protections must not be removed, disabled, or circumvented.
• Competing use is restricted until the Apache-2.0 change date for that version.
• Redistribution must keep applicable notices and license terms.

Source of truth

When there is any ambiguity, treat these as authoritative:

• LICENSE.md
• each package's package.json license field
• package-level notices/headers where applicable

By submitting a contribution, you agree that your changes are provided under the license terms applicable to the files/packages you modify.

Community standards

• Follow our Code of Conduct.
• Be respectful in reviews and discussions.
• Prefer constructive, evidence-based feedback.

Thanks for contributing to Hexabot.