Contributor quickstart

Goal

Prepare a Superbee development checkout, make one bounded change, run the relevant proofs, and hand off the exact commit for CI review. This how-to is for contributors with Node.js, npm, and Git.

The workflow follows the repository's tagged CONTRIBUTING.md.

Supported development environment

• Node.js 20 or newer.

• npm with the repository lockfile.

• Git.

• macOS, Linux, or Windows for the public package; individual scripts can document narrower needs.

Use the repository's existing branch and worktree conventions. Preserve unrelated local changes.

1. Install the exact dependency graph

From the repository root:

npm ci

npm ci is the reproducible starting point. Do not replace the lockfile or run broad dependency upgrades as part of an unrelated change.

2. Orient before editing

Read the repository instructions and locate the owning package:

git status --short --branch
sed -n '1,240p' CLAUDE.md
find packages -maxdepth 2 -name package.json -print

Use rg to find the public contract, implementation, and tests for the behavior. Superbee keeps semantics in core and treats CLI, HTTP, UI, MCP, setup, and publication as interfaces over those semantics. Change the narrowest owning layer and preserve cross-interface parity.

3. Establish a clean baseline

Run the repository-wide compile checks before the change:

npm run build
npm run typecheck

If either fails on the starting commit, record that baseline before editing. Do not hide a known failure by weakening checks.

4. Make the smallest coherent change

Update the governing implementation, its public contract or help, and its behavior proof together. Common coupled surfaces include:

• command behavior, executable help, structured output, and CLI tests;

• storage semantics, all relevant backend adapters, wire contract, and parity tests;

• recipe definitions, parser or planner behavior, built-in references, and recipe journeys;

• View bridge shape, runtime enforcement, authoring reference, and UI or MCP host tests;

• publication schema, generated types, packed exports, and external-consumer tests.

Generated files stay generator-owned. Run the documented generator and commit its deterministic output; never patch a generated projection as the only source change.

5. Run targeted proofs first

Use the owning workspace's test command while iterating. Examples:

npm test --workspace @superbee/core
npm test --workspace superbee
npm test --workspace @superbee/publication

Then run the root checks that cover affected boundaries:

npm run build
npm run typecheck
npm test

Follow any additional command named in CONTRIBUTING.md, the package manifest, or changed schema. When the behavior crosses packaging, test the packed superbee tarball from an isolated prefix and invoke that installed executable rather than the adjacent development checkout.

6. Review the exact diff and commit

git diff --check
git status --short
git diff
git commit -m "Describe the verified behavior"

Confirm every changed file belongs to the intended behavior. Include generated artifacts only when their source changed and their checks pass.

CI boundary

GitHub Actions is authoritative for the exact pushed commit SHA. A local green run proves the local worktree; it does not prove a different remote revision. After pushing, verify that the required workflow ran against the intended SHA and preserve the workflow URL in the pull request or release evidence.

Do not amend or force-push while another reviewer is validating an earlier SHA without clearly resetting that review boundary.

Security and disclosure

Follow the private vulnerability-reporting process in SECURITY.md. Keep credentials, private-state contents, and exploitable details out of commits, public issues, test fixtures, and Superbee bundles.

Recovery

Next actions

Architecture contributors should begin with Architecture at a glance and Bundle engine and storage seam. CLI changes must also review CLI commands and its documentation trigger.