Contributor guide

Make changes small enough to prove.

SkyTwin is a TypeScript monorepo with security and product claims tightly coupled to implementation. A contribution is complete only when its behavior, tests, and relevant documentation agree.

Set up a development tree

pnpm install
pnpm build
pnpm test
pnpm lint

Node 20+ and pnpm are required. Development services use CockroachDB through its PostgreSQL wire protocol. Use pnpm db:migrate and pnpm db:seed when the change needs local data. The repository engineering guide documents stale build outputs and the serial-build workaround for the known local Turbo race.

A contribution workflow

Find or open an issue that describes the problem and its scope.
Trace the relevant typed contract and the policy/explanation path before changing behavior.
Make the narrowest change that satisfies the behavior; add unit tests alongside parsing, validation, policy, or safety changes.
Run focused tests first, then the relevant package/full checks.
Open a pull request; describe user-visible behavior, verification, documentation impact, and any remaining boundary.

Safety invariants are not optional

Never auto-execute without a policy check.
Always record explanations for actions and deliberate non-actions on supported paths.
Respect trust tiers and hard spend limits.
Classify reversibility accurately and include risk assessment for every candidate.
Route feedback from approvals, rejections, edits, and undos back to the twin model.
Do not weaken provenance: missing provenance must fail safe to untrusted external.

If a change alters the decision path: review the policy engine, injection guard, execution router, explanation record, and feedback flow together. Passing TypeScript alone does not prove the action is safe.

Review and documentation discipline

All changes go through a pull request; do not push directly to main. The expected gate is structural review, automated review where available, tests/CI, and release-documentation alignment. For public copy, preserve the source-of-truth release claim ledger: a feature existing in a branch is not automatically a public support claim.

Documentation about engine behavior should point to the source file that constrains it. Update the README, changelog, architecture, safety, and release material only when the final diff supports the statement.

Issues and security reports

Use GitHub issues for reproducible defects, product proposals, and documentation gaps. Keep tokens, account data, private logs, and sensitive proof out of public threads. For a change that needs external credentials, deployment, signing, notarization, or third-party verification, document the blocker rather than fabricating local evidence.