README

Chorus is the meta-layer for the Decode Labs ecosystem. Where the individual packages contain user-facing code and documentation, Chorus provides the architectural map, cross-cutting decisions, and package index that define how the entire suite fits together.

Chorus is not a runtime library. It is the reference point for humans and AI assistants when designing, documenting, and evolving Decode Labs packages and projects built on top of them.

Purpose

Chorus exists to:

Describe the overall architecture of the Decode Labs ecosystem.
Maintain a canonical index of all packages, including their roles, milestones, and dependencies.
Host cross-package documentation, such as coding standards, naming rules, error-handling strategy, and architectural principles.
Record Decision Documents (ADRs) that explain the rationale behind major choices.
Provide a stable place for high-level specifications and design discussions that span multiple repositories.

Package-specific documentation remains in each package’s own repository. Chorus focuses only on the parts that bind those packages together.

What Chorus Contains

1. Package Index

A machine-readable description of every Decode Labs package:

Name
Repository location
Role and responsibility
Language
Dependencies
Milestone/stability
Documentation references

2. Architecture Documentation

System-level guides explaining:

How packages relate to one another
Intended dependency directions
Architectural “clusters”
Core concepts shared across repositories

3. Decision Records (ADRs)

A curated log of cross-cutting decisions:

Error model
Logging and observability
Naming conventions and coding standards
Discovery mechanisms (e.g. Archetype)
Deprecation and backwards-compatibility strategy

ADRs help ensure long-term consistency as the ecosystem grows.

4. Workflow & Standards

Guidelines that define how Decode Labs packages should:

Be structured
Expose public APIs
Document behaviour
Introduce or evolve features
Interact with AI assistants, Cursor, and code generators

5. Templates

Standard templates for package documentation:

README templates
Package specification templates
Feature specification templates
Change specification templates
AGENTS.md templates

Note: Templates live in Chorus, but the actual specs and documentation created from these templates live in their respective package repositories.

6. Change Specs

Meta-level change specifications that describe ecosystem-wide behavioural changes and migration plans:

Located in docs/meta/releases/<package>/...
Coordinate changes across multiple repositories
Define migration strategies for libraries, frameworks, and client projects

Note: Change Specs live in Chorus because they coordinate ecosystem-wide migrations. Package-specific implementation specs (package specs and feature specs) live in package repositories.

What Chorus Does Not Contain

Runtime code
Package-specific implementation specs (package specs live in docs/meta/spec.md in each package repo)
Feature specs (live in docs/meta/features/ in each package repo)
User-facing package documentation (READMEs, usage examples, etc.)
Tests
Implementations

Those belong in their respective package repositories. Chorus is purely an architectural and organisational layer.

Contributing

Contributions to Chorus should focus on:

Improving architectural clarity
Adding or refining decision documents
Updating the package index
Enhancing cross-package documentation
Recording discussions and design rationale

Changes that affect a specific package’s behaviour should be made in that package’s repository, with Chorus updated only if the change has architectural or ecosystem-wide significance.

Licence

Chorus is licensed under the MIT License. See LICENSE for the full license text.

decodelabs / chorus

Maintainers

Details