Contributing

This section is the contributor-facing handbook for working on the plexsphere repository. Read it before opening a pull request — the gates documented here run in CI, and a red gate is the most common reason a PR sits unmerged.

The handbook is grouped by the order a contributor typically needs the information: first the lay of the land and the toolchain, then how to test and how CI verifies the change, then the surfaces (API, dashboard, docs) each with their authoring rules, and finally the contributor tooling that helps with audits and previews.

Orient yourself

Read these first when you join the repository or come back to it after a long absence.

• Repository layout and bounded-context map — where each internal/<context>/ package belongs, the binaries under cmd/, and the depguard rules that enforce the boundaries.
• Toolchain pins and upgrade procedure — the single source of truth for Go, golangci-lint, GitHub Actions, SPDX headers, container images, and every other build-time pin.

Test and verify a change

How the test pyramid is organised and what CI runs on every PR.

• Testing — pyramid, build tags, and the shared harness — the unit / integration / E2E tiers, the integration build tag, the shared internal/platform/testutil primitives, and the rendered-surface rule on every failure message.
• CI pipeline — jobs, triggers, and reproducing failures — every CI job mapped to its local make target, the path-based skipping rules, the cache layers, and the per-tool reproduction recipes for a red run.

Evolve the /v1 API surface

Both pages target the /v1 HTTP surface — one is the spec workflow and codegen, the other is the runtime UI that renders the spec.

• OpenAPI-first contract and code generation — the authoring loop for api/openapi/plexsphere-v1.yaml, additive vs. breaking-change rules, deprecation and sunset signalling, and the four generated artefact trees the drift gate enforces.
• Embedded ReDoc UI for /v1/docs — the vendored ReDoc bundle, the supply-chain-safe upgrade procedure, the security headers the handler emits, and the authn/authz bypass entries that let the page render without credentials.

Author and maintain the docs corpus

The rules that keep the docs corpus consistent, traceable, and free of internal task identifiers, plus how to preview the site locally.

• Docs authoring conventions — sentence-case headings, the five-field frontmatter contract, and the rule that internal task identifiers never reach the rendered output.
• Traceability identifier conventions — repository-wide map of which surfaces may carry planwerk task ids, requirement ids, and review-item codes, plus the regression gate that keeps them out of rendered surfaces.
• Previewing and building the docs site locally — make docs-preview, make docs-build, make docs-publish, the pinned VitePress tooling, and the worked example for adding a new page to the sidebar.

Contributor tooling

• Claude Code skills — the repository-specific audit skills under .claude/skills/, what each one covers, how to invoke them, and how their deterministic scripts pair with the CI gates.

When to read this section

• You are setting up a development environment for the first time — start with layout and toolchain.
• A CI job is failing and you want the local reproduction recipe — see the CI pipeline guide.
• You are about to author a new doc page and need the heading and frontmatter rules — see authoring conventions and the docs-preview worked example.
• You are introducing a new bounded context, a new CI job, or a new top-level binary — see layout and CI, and remember the lockstep gates the audit skills in claude-skills cover.