Skip to content

Contributing ​

How to work on Ensemble code and documentation. Start with the repository CONTRIBUTING.md and AGENTS.md; this hub collects the contributor-only documentation that used to sit in the main docs index.

Before you start ​

  1. Read CONTRIBUTING.md for setup, verification, and pull-request expectations.
  2. Read AGENTS.md and the domain glossary.
  3. Follow the issue tracker workflow and the triage labels.
  4. For TUI or host integration work, read the OpenCode/OpenTUI runtime guide.

Documentation work ​

  • Documentation style guide: voice, canonical terms, page template, code samples, visuals, and review checklist.
  • Redirect map: old docs-index entries and their new homes.
  • Docs home: the user navigation this work must keep accurate.
  • Evidence index: ADRs, verification records, implementation notes, assessments, and compatibility evidence.

Build the docs site locally with npm run docs:site and publish-preview it with npm run docs:site:preview. npm run docs:site:build runs the sidebar, reachability, redirect, SEO, sitemap, generated-artifact, and built-anchor checks before the VitePress build. npm run docs:check is the full local gate: Markdown lint, inventory, frontmatter, links and rendered anchors, Markdown fences, shell syntax, canonical version/host/Node claims, generated reference freshness, media, the VitePress build, and the built-site anchor crawl. CI runs npm run docs:check:fast in the separate Docs job; the Docs site job owns the single VitePress build. Fixture tests use the explicit --skip-site-build mode.

Update user documentation when externally visible behavior changes. If no doc update is needed, put a docs-not-needed: <reason> line in the pull request body; the docs-rationale workflow checks the changed-file list and PR body from the trusted base checkout. It is not yet a required status check on main: adding it needs an explicit maintainer decision and a GitHub ruleset change, which this repository does not configure. Until then the workflow is advisory and the program merge can proceed without claiming external enforcement. Keep ADRs and verification records public, but do not put them in the primary user navigation; link them from the evidence index or as a Go deeper link at the end of a concept page.

The Docs site workflow builds the Pages artifact on pull requests and deploys only from main after the repository's Pages environment is enabled. Enabling Pages and publishing the site are external maintainer actions; this branch does not deploy the site or claim that it is live.

Review and process ​

DocumentPurpose
Review workflowThe two-axis review process
Reviewer standardsJudgement calls that stay manual
Handoff contractServer-owned completion, migration handoff, batch review, loop guards, and mentions
Domain document conventionsGlossary and ADR conventions

Architecture and evidence ​

ResourceWhat it contains
ADR indexEvery accepted architecture decision
Evidence indexCurrent and historical verification records
Implementation notesService, TUI, storage, native tools, and acceptance notes
OpenTUI assessmentHistorical host-evaluation evidence
OpenCode host support rangeSupported CLI releases, peer range, and runtime warning
OpenCode 2.2.1 compatibility reportHistorical extension behavior and gaps

Boundaries ​

  • Keep credentials, conversation content, and private paths out of the repository and public issues. The support policy lists the redaction rules.
  • Do not rewrite an ADR or verification record to match a new claim; add a new record or supersede the decision.
  • Do not hand-maintain generated reference lists. Run npm run docs:reference after changing a catalog; npm run docs:check fails when a generated page is stale, missing, or unreachable from the reference index.

Released under the MIT License.