Summary
This proposal recommends a minimal restructure of the FINOS Architecture as Code project to accommodate CALM Suite (CALM Guard, CALM Studio, CALM Learning) and create a cleaner schema development process. Two new repositories are created — one for governance documentation and one for the CALM Meta Schema — and the existing monorepo absorbs the incoming CALM Suite components alongside its current contents.
| Repository |
Status |
Contents |
| calm-governance |
new |
Project-wide governance, contribution guidelines, code of conduct |
| calm-schema |
new |
CALM Meta Schema, schema documentation, validation test suite |
| architecture-as-code |
existing |
CLI, server, shared libraries, calm-models, calm-widgets, calm-ai, CALM Hub, CALM Hub UI, VS Code Extension, CALM Studio, CALM Guard, CALM Learning, docs |
As part of this restructure, we propose rebranding the FINOS project from "Architecture as Code" to CALM. The CALM name is already how the project is known within the community and externally. Aligning the FINOS project name with the brand provides consistent naming across repositories, documentation, and the FINOS landscape. The three repos would sit under a single CALM project in the FINOS registry, strengthening the project's position for progression to FINOS Graduated status.
This restructure is deliberately conservative. Rather than breaking the monorepo into multiple component repositories, we extract only what benefits materially from being separate — the schema (which needs a cleaner development workflow) and the governance documentation (which belongs in a neutral, code-free location). The established platform tooling, the new CALM Suite components, and the foundational libraries all continue to live together in the existing repository, preserving the benefits of monorepo development while welcoming new contributors into the same codebase as the existing maintainers.
Rationale
Why Extract the Schema
The schema has a fundamentally different character to the tooling built on top of it. It changes infrequently, it has its own governance process with formal review and testing periods, and it is the artefact that defines the contract between all CALM tools — including tools built outside this project by third parties.
Extracting the schema into its own repository provides two concrete benefits.
First, it simplifies the schema change process. The current approach — developing changes via draft and release folders within the monorepo — has proven confusing for contributors. A standalone repository enables a cleaner feature-branch workflow where each proposed schema change is developed, reviewed, and tested on its own branch before merging to main. The revised process is described below.
Second, it enables independent versioning and publishing. Schema versions become explicit, published npm artefacts that the CLI (and any third-party tooling) can depend on. A schema release is a deliberate, visible act — not a side-effect of a CLI refactor.
Why Extract Governance
Governance documentation belongs in a neutral, code-free location. Housing the project's governance, contribution guidelines, and code of conduct alongside source code in any single repository implies that repository is the "home" of the project, which doesn't fit a multi-repo project and can be misleading even today. A dedicated calm-governance repository makes the governance clearly visible and neutral to any codebase, and provides a single authoritative source that all other repositories reference.
Why Keep Everything Else Together
The existing monorepo works. The CLI, server, CALM Hub, Hub UI, VS Code extension, shared libraries, data models, and visualisation components are already developed together with shared build infrastructure, atomic cross-cutting changes, and a coordinated test suite. Breaking this up has real costs — cross-repo CI, coordinated releases, duplicated tooling — and for our current scale those costs outweigh the benefits.
Adding CALM Suite (CALM Studio, CALM Guard, CALM Learning) into the same repository has two important benefits. First, it forces structural coordination: the VS Code extension, CALM Hub, and CALM Studio all operate in overlapping space, and co-locating them ensures the teams building them are reading each other's code and coordinating on features rather than accidentally duplicating functionality. Second, it embeds the incoming CALM Suite team alongside the existing maintainers in the same codebase, supporting genuine collaboration rather than parallel development.
If the project grows to the point where the monorepo becomes difficult to manage — due to contributor scale, build times, or divergent release cadences — further restructuring can be considered. That is not today's problem.
Repository Structure
calm-governance
The governance home. This repository holds no code — it contains the project-wide governance documentation, contribution guidelines, and code of conduct that apply across all CALM repositories.
calm-governance/
├── GOVERNANCE.md # Project-wide governance (roles, decision making, processes)
├── CONTRIBUTING.md # General contribution guidelines
├── CODE_OF_CONDUCT.md # FINOS Code of Conduct
└── README.md
Each code repository's CONTRIBUTING.md references this repository as the authoritative source for project governance.
calm-schema
The specification. This repository contains the CALM Meta Schema, its documentation, and a comprehensive validation test suite.
calm-schema/
├── schema/ # CALM Meta Schema (JSON Schema definitions)
├── tests/ # Schema validation test suite
├── examples/ # Example patterns and architectures
├── CONTRIBUTING.md # References GOVERNANCE.md in calm-governance
└── README.md
The main branch contains the current version of the schema. There are no version folders — the schema files are edited in place. Schema development happens on feature branches, and releases are tagged with semantic versions.
Publishing. calm-schema is published as an npm package (@finos/calm-schema). Each release publishes a single version of the schema to the npm registry (e.g., @finos/calm-schema@1.0.0, @finos/calm-schema@1.1.0, @finos/calm-schema@2.0.0). Previous versions remain available in the npm registry and as git tags.
Multi-version support. The CLI needs to validate CALM documents against the schema version those documents declare. At build time, the CLI bundles the set of schema versions it supports by pulling specific versions from the npm registry. Adding support for a new schema version in the CLI is a change in the main repo: update the bundled version set, adjust any validation logic, and release.
architecture-as-code (existing monorepo)
The main repository. This continues to host the CALM platform and analysis tooling as a multi-project monorepo.
architecture-as-code/
├── cli/ # @finos/calm-cli (TypeScript)
├── server/ # HTTP server proxying CLI commands
├── shared/ # Shared TypeScript utilities
├── calm-models/ # TypeScript data models
├── calm-widgets/ # React visualisation components
├── calm-ai/ # AI agent tools and prompts
├── calm-hub/ # Java/Quarkus REST API backend
├── calm-hub-ui/ # React frontend for CALM Hub
├── calm-vscode/ # VS Code extension (renamed from calm-plugins/vscode)
├── calm-suite/
├── calm-studio/ # Interactive architecture editor
├── calm-guard/ # Compliance and security evaluatio
└── calm-learning/ # Deterministic rule extraction from AI scanning
├── docs/ # Docusaurus documentation site
├── CONTRIBUTING.md # References GOVERNANCE.md in calm-governance
└── README.md
The repository depends on @finos/calm-schema and consumes schema versions from the npm registry rather than referencing local files.
Schema Change Process
The current schema governance process uses a folder-based approach: changes are proposed and developed in a draft/ folder, validated, then promoted to a releases/ folder via release candidates. This approach has caused confusion — it is unclear what constitutes the current schema at any given time, draft changes can accumulate without resolution, and the folder structure adds navigational overhead for contributors.
The standalone calm-schema repository enables a simpler feature-branch workflow.
Proposing a change. Schema changes are proposed via a GitHub Issue using the Schema Change Proposal template. The issue must describe the motivation, the proposed change, and the impact on existing tooling. Examples demonstrating the change should be included.
Developing a change. Each approved proposal is developed on a feature branch (e.g., feature/893-add-data-node-type). The branch contains the modified schema files alongside updated validation tests. CI runs the schema test suite on every push to the feature branch.
Cross-project validation. When a feature branch is ready for review, CI triggers downstream validation: the main repo's test suite is run against the proposed schema. If tests fail, the schema change either needs adjustment or the main repo needs a corresponding update, coordinated via a linked PR.
Review and approval. The PR from the feature branch to main requires approval from at least one member of the calm-schema-governance group. Review considers correctness, backward compatibility, downstream impact, and alignment with the project's direction.
Release. When a schema change is merged to main, the package is published to npm with the new version number and a git tag is created. Releases use semantic versioning. Minor releases (backward-compatible additions) can be proposed at any time. Major releases (breaking changes) require a migration guide and coordination with the main repo maintainers.
What this replaces. The draft and releases folder structure in the existing monorepo is retired. The schema is edited in place on feature branches — there is no need to copy the current version into a new folder before making changes. Previous versions are preserved as git tags and npm registry releases, not as folders in the repository.
Release Process
calm-schema
calm-schema has a single package and a single versioning stream. Each release is tagged (e.g., v1.2.0) and a corresponding GitHub Release is created. Previous versions are available via npm and git tags.
Main repository (multiple projects, independent releases)
The main repository contains multiple projects that release independently. Each project has its own versioning stream and its own GitHub Releases.
Consistent major version, independent minor and patch versions. All projects within the repository share a consistent major version but release minor and patch versions independently as changes are ready. For example, at a point in time the projects might have:
| Project |
Version |
| CALM CLI |
2.3.1 |
| CALM Server |
2.2.0 |
| CALM Hub |
2.1.2 |
| CALM Hub UI |
2.1.1 |
| CALM VS Code |
2.2.0 |
| CALM Studio |
2.1.0 |
| CALM Guard |
2.1.1 |
| CALM Learning |
2.0.1 |
The shared major version (2.x.x) signals compatibility: all projects at major version 2 are designed to work together and target the same major version of their upstream dependencies (calm-schema and any shared libraries within the repo). Individual projects ship features and fixes at their own pace.
Major version bumps are coordinated across all projects in the repository simultaneously. A major version increment signals a breaking change — for example, a new calm-schema major version that requires changes across multiple projects, or a breaking change in a shared library. Major version bumps are proposed by the Project Maintainers and require agreement across the maintainer group before release.
Minor and patch releases are managed by the maintainers of the individual project. A minor release adds backward-compatible functionality; a patch release fixes a bug. These do not require coordination beyond the normal PR review process.
Git Tags and GitHub Releases in a Multi-Project Repo
Because a single repository hosts multiple independently-released projects, git tags and GitHub Releases are prefixed with the project name to disambiguate them. This is the standard approach used by mature multi-project repositories (Argo, Kubernetes SIGs, Lerna-based monorepos, and many others).
Tag format: <project>/v<major>.<minor>.<patch>
Examples:
calm-hub/v2.1.2
calm-hub/v2.1.3
calm-studio/v2.1.0
calm-cli/v2.3.1
calm-vscode/v2.2.0
Each tag maps to a GitHub Release with the same name. The GitHub Releases page for the repository shows all releases across all projects in a single feed, which makes it easy for users to see what has shipped recently. Filtering by tag prefix (e.g., searching for calm-hub/) shows the release history for a specific project.
Published package versions on npm and Maven Central follow standard semver without the prefix — @finos/calm-cli@2.3.1, not @finos/calm-cli@calm-cli/v2.3.1. The prefix is only used for git tags and GitHub Release names, where it disambiguates one project's releases from another's within the same repository.
Release notes. Each GitHub Release contains release notes for that project's changes only, scoped to commits that touched the project's directory. This is achieved through conventional commit scopes (e.g., feat(calm-hub): add authentication) combined with tooling that filters changelogs by scope.
Release workflow. Releases are triggered by creating a prefixed tag. CI detects the tag prefix, builds the corresponding project, runs the test suite, publishes the package to the appropriate registry (npm for TypeScript, Maven Central for Java), and creates the GitHub Release with auto-generated release notes. Tooling such as semantic-release-monorepo or changesets automates this workflow; the choice of tool is a repository-level decision for the maintainers.
Schema Version Adoption
When calm-schema publishes a new version, the main repository adopts it through a PR that updates the pinned @finos/calm-schema version and makes any necessary adjustments to the CLI, shared libraries, or data models. This is a deliberate, reviewed update rather than an automatic side-effect. Renovate or Dependabot can raise the PR; the maintainers decide when to merge it.
For minor and patch schema releases (backward-compatible), adoption happens when convenient. For major schema releases (breaking changes), adoption is coordinated with a corresponding major version bump across all projects in the main repository.
Governance
Single Project, Single Governance
All three repositories operate under a single governance structure defined in calm-governance.
Roles
Lead Maintainer. The project's interface with the FINOS team and board. Responsible for approving quarterly project reports and representing the project externally. Elected by the Project Maintainer group.
Project Maintainers. The senior maintainer group responsible for the overall direction of the project. Project Maintainers have merge authority across all repositories and are responsible for cross-cutting decisions including schema changes, new sub-project admission, and governance amendments.
Repository Maintainers. Contributors who have been granted merge authority over a specific repository. Repository Maintainers manage the day-to-day development of their repository: reviewing PRs, managing releases, and setting the roadmap within the bounds established by the Project Maintainers.
Contributors. Anyone who submits a contribution to any repository. Contributors follow the standard FINOS contribution process (CLA, PR review, conventional commits).
Becoming a Repository Maintainer
Contributors earn Repository Maintainer status through sustained, quality contribution to a specific repository.
calm-schema. Schema maintainers must demonstrate a deep understanding of the CALM specification, JSON Schema, and the impact of schema changes on downstream tooling. Candidates are expected to have authored or substantially contributed to multiple schema change proposals, participated in schema reviews, and shown good judgement on backward compatibility. Nomination is by an existing calm-schema maintainer or Project Maintainer, with approval by the calm-schema-governance group.
Main repository (calm). Maintainers must demonstrate sustained contribution to one or more projects within the repository. Candidates are expected to have a track record of merged PRs, participation in code review and issue triage, and an understanding of how their project relates to the other tools in the repository. Nomination is by an existing maintainer or Project Maintainer, with approval by the main repo maintainer group.
In all cases, the nominator should open an issue in calm-governance citing the candidate's contribution history. The relevant maintainer group reviews and approves by consensus.
Becoming a Project Maintainer
Repository Maintainers may be nominated for Project Maintainer status by an existing Project Maintainer. Promotion reflects contribution and commitment beyond a single repository — candidates are expected to have demonstrated sustained contribution across the project, good judgement on cross-cutting concerns, and alignment with the project's overall direction. Approval is by consensus of the existing Project Maintainers.
This is the standard open source meritocratic model: authority is earned through contribution over time.
Decision Making
Day-to-day decisions within a repository are made by that repository's maintainers. Cross-cutting decisions — including schema changes, new repository creation, and governance changes — are made by the Project Maintainers, seeking consensus with a simple majority vote as fallback.
Schema changes follow the feature-branch process described above: proposal via issue, development on a feature branch with CI validation, cross-project testing, and approval by the calm-schema-governance group.
Code Ownership
The main repository uses a CODEOWNERS file to ensure that changes to specific projects require review from the maintainers with subject matter expertise. CODEOWNERS maps each project directory to the maintainers responsible for it — changes to cli/ require approval from the CLI maintainers, changes to calm-guard/ require approval from the CALM Guard maintainers, and so on.
This ensures every PR is reviewed by someone with deep knowledge of the affected code, regardless of who submits it. A contribution to CALM Hub from a CALM Studio developer still requires sign-off from a CALM Hub maintainer. It also enables fine-grained oversight within a monorepo without fragmenting the repository itself — projects share a codebase and build infrastructure, but each has designated reviewers accountable for its quality and direction.
CODEOWNERS is enforced via GitHub branch protection rules. PRs cannot be merged without approval from the designated owners for all affected paths. The CODEOWNERS file is itself owned by the Project Maintainers.
GitHub Teams
The governance roles and code ownership model are implemented through GitHub Teams within the finos organisation.
Project-level teams:
| Team |
Purpose |
Permissions |
calm-project-maintainers |
Project Maintainers with authority across all repos |
Maintain on all three repositories. Owns the CODEOWNERS files. |
calm-schema-governance |
Schema change reviewers — a subset of schema and project maintainers responsible for approving schema PRs |
Write on calm-schema |
Repository-level teams:
| Team |
Purpose |
Permissions |
calm-schema-maintainers |
Maintainers of the CALM Meta Schema |
Maintain on calm-schema |
calm-maintainers |
Maintainers of the main repository |
Maintain on calm |
CODEOWNERS teams (per-project within the main repository):
| Team |
Paths |
calm-cli-owners |
/cli/, /server/ |
calm-shared-owners |
/shared/, /calm-models/, /calm-widgets/ |
calm-ai-owners |
/calm-ai/ |
calm-hub-owners |
/calm-hub/, /calm-hub-ui/ |
calm-vscode-owners |
/calm-vscode/ |
calm-studio-owners |
/calm-studio/ |
calm-guard-owners |
/calm-guard/, /calm-learning/ |
calm-docs-owners |
/docs/ |
A contributor may be a member of multiple teams. Project Maintainers are automatically members of all repository-level teams.
CODEOWNERS teams are intentionally granular. A PR that touches both calm-hub/ and calm-studio/ requires approval from both calm-hub-owners and calm-studio-owners, ensuring cross-project changes are reviewed by the relevant subject matter experts.
Team membership is managed by the calm-project-maintainers team. Changes to team membership should be reflected in an issue in calm-governance for transparency.
Meetings
The existing monthly community meetup and weekly Office Hours continue to cover the full project. All repositories are discussed in these forums. Working sessions can be scheduled as needed but are open to all project participants.
FINOS Reporting
All three repositories are registered under the CALM FINOS project. Contributor metrics from all repos roll up into a single project dashboard, supporting the path to Graduated status. Contributors from Sonatype, ArchRails, and other organisations working on CALM Suite components count towards the multi-organisation contributor requirement.
The updated FINOS Project Lifecycle (March 2026) renamed the previous "Active" stage to "Graduated" and introduced regular TOC health reviews every six months for Incubating and Graduated projects. The restructure proposed here directly supports the Graduated acceptance requirements: clear governance documentation, multi-organisation contribution, and alignment with the OpenSSF Security Baseline at Maturity Level 3.
Migration Plan
Phase 1: Governance
Create the calm-governance repository under the finos GitHub organisation. Draft and agree the GOVERNANCE.md with all current maintainers. This must be approved before any structural changes to code repositories.
Phase 2: Schema Extraction
Create the calm-schema repository under the finos GitHub organisation. Migrate the current released schema files (without version folders — the schema is edited in place), along with validation tests and examples. Existing drafts are converted to feature branches. Establish the feature-branch workflow, CI pipeline, and npm publishing. Tag and publish the current schema as the initial @finos/calm-schema release, and publish previous schema releases to npm so the full version history is available in the registry.
Phase 3: Main Repository Updates
Update the existing monorepo:
- Remove the migrated schema files.
- Update the CLI to bundle supported schema versions from the
@finos/calm-schema npm registry rather than referencing local files.
- Rename
calm-plugins/vscode to calm-vscode at the top level.
- Configure the prefixed tag release workflow (
<project>/v<major>.<minor>.<patch>) and adopt release tooling (e.g., semantic-release-monorepo or changesets).
- Set up the CODEOWNERS file and associated GitHub teams.
- Rename the repository from
architecture-as-code to calm.
Phase 4: CALM Suite Integration
CALM Studio, CALM Guard, and CALM Learning are contributed into the main repository. The CALM Suite team are granted Repository Maintainer status for the main repo and added to the relevant CODEOWNERS teams.
Phase 5: FINOS Formalisation
Open a FINOS issue to formally record the Project Maintainers' endorsement of CALM Suite's inclusion. Update LFX reporting to ensure all three repositories are linked to the CALM project. Confirm with Morgan Stanley OSPO that the existing contribution approval covers the new repositories. Submit the project rebranding request to FINOS to update the project name from Architecture as Code to CALM across the FINOS landscape, registry, and reporting dashboards.
What This Structure Achieves
It welcomes CALM Suite into the project by embedding the incoming components directly in the existing codebase alongside the existing maintainers. It gives the schema a cleaner development workflow that eliminates the confusion of the current draft/releases folder approach. It establishes project-wide governance in a neutral, code-free location. It preserves the monorepo benefits of atomic cross-cutting changes, shared build infrastructure, and natural coordination between teams. It supports progression to FINOS Graduated status by aggregating all contributors under a single project and establishing the governance transparency that the TOC health review process requires. And it avoids premature restructuring — if the project grows to a scale where further splits are warranted, that decision can be made at that point, on evidence.
Summary
This proposal recommends a minimal restructure of the FINOS Architecture as Code project to accommodate CALM Suite (CALM Guard, CALM Studio, CALM Learning) and create a cleaner schema development process. Two new repositories are created — one for governance documentation and one for the CALM Meta Schema — and the existing monorepo absorbs the incoming CALM Suite components alongside its current contents.
As part of this restructure, we propose rebranding the FINOS project from "Architecture as Code" to CALM. The CALM name is already how the project is known within the community and externally. Aligning the FINOS project name with the brand provides consistent naming across repositories, documentation, and the FINOS landscape. The three repos would sit under a single CALM project in the FINOS registry, strengthening the project's position for progression to FINOS Graduated status.
This restructure is deliberately conservative. Rather than breaking the monorepo into multiple component repositories, we extract only what benefits materially from being separate — the schema (which needs a cleaner development workflow) and the governance documentation (which belongs in a neutral, code-free location). The established platform tooling, the new CALM Suite components, and the foundational libraries all continue to live together in the existing repository, preserving the benefits of monorepo development while welcoming new contributors into the same codebase as the existing maintainers.
Rationale
Why Extract the Schema
The schema has a fundamentally different character to the tooling built on top of it. It changes infrequently, it has its own governance process with formal review and testing periods, and it is the artefact that defines the contract between all CALM tools — including tools built outside this project by third parties.
Extracting the schema into its own repository provides two concrete benefits.
First, it simplifies the schema change process. The current approach — developing changes via draft and release folders within the monorepo — has proven confusing for contributors. A standalone repository enables a cleaner feature-branch workflow where each proposed schema change is developed, reviewed, and tested on its own branch before merging to main. The revised process is described below.
Second, it enables independent versioning and publishing. Schema versions become explicit, published npm artefacts that the CLI (and any third-party tooling) can depend on. A schema release is a deliberate, visible act — not a side-effect of a CLI refactor.
Why Extract Governance
Governance documentation belongs in a neutral, code-free location. Housing the project's governance, contribution guidelines, and code of conduct alongside source code in any single repository implies that repository is the "home" of the project, which doesn't fit a multi-repo project and can be misleading even today. A dedicated calm-governance repository makes the governance clearly visible and neutral to any codebase, and provides a single authoritative source that all other repositories reference.
Why Keep Everything Else Together
The existing monorepo works. The CLI, server, CALM Hub, Hub UI, VS Code extension, shared libraries, data models, and visualisation components are already developed together with shared build infrastructure, atomic cross-cutting changes, and a coordinated test suite. Breaking this up has real costs — cross-repo CI, coordinated releases, duplicated tooling — and for our current scale those costs outweigh the benefits.
Adding CALM Suite (CALM Studio, CALM Guard, CALM Learning) into the same repository has two important benefits. First, it forces structural coordination: the VS Code extension, CALM Hub, and CALM Studio all operate in overlapping space, and co-locating them ensures the teams building them are reading each other's code and coordinating on features rather than accidentally duplicating functionality. Second, it embeds the incoming CALM Suite team alongside the existing maintainers in the same codebase, supporting genuine collaboration rather than parallel development.
If the project grows to the point where the monorepo becomes difficult to manage — due to contributor scale, build times, or divergent release cadences — further restructuring can be considered. That is not today's problem.
Repository Structure
calm-governance
The governance home. This repository holds no code — it contains the project-wide governance documentation, contribution guidelines, and code of conduct that apply across all CALM repositories.
Each code repository's CONTRIBUTING.md references this repository as the authoritative source for project governance.
calm-schema
The specification. This repository contains the CALM Meta Schema, its documentation, and a comprehensive validation test suite.
The main branch contains the current version of the schema. There are no version folders — the schema files are edited in place. Schema development happens on feature branches, and releases are tagged with semantic versions.
Publishing. calm-schema is published as an npm package (
@finos/calm-schema). Each release publishes a single version of the schema to the npm registry (e.g.,@finos/calm-schema@1.0.0,@finos/calm-schema@1.1.0,@finos/calm-schema@2.0.0). Previous versions remain available in the npm registry and as git tags.Multi-version support. The CLI needs to validate CALM documents against the schema version those documents declare. At build time, the CLI bundles the set of schema versions it supports by pulling specific versions from the npm registry. Adding support for a new schema version in the CLI is a change in the main repo: update the bundled version set, adjust any validation logic, and release.
architecture-as-code (existing monorepo)
The main repository. This continues to host the CALM platform and analysis tooling as a multi-project monorepo.
The repository depends on
@finos/calm-schemaand consumes schema versions from the npm registry rather than referencing local files.Schema Change Process
The current schema governance process uses a folder-based approach: changes are proposed and developed in a
draft/folder, validated, then promoted to areleases/folder via release candidates. This approach has caused confusion — it is unclear what constitutes the current schema at any given time, draft changes can accumulate without resolution, and the folder structure adds navigational overhead for contributors.The standalone calm-schema repository enables a simpler feature-branch workflow.
Proposing a change. Schema changes are proposed via a GitHub Issue using the Schema Change Proposal template. The issue must describe the motivation, the proposed change, and the impact on existing tooling. Examples demonstrating the change should be included.
Developing a change. Each approved proposal is developed on a feature branch (e.g.,
feature/893-add-data-node-type). The branch contains the modified schema files alongside updated validation tests. CI runs the schema test suite on every push to the feature branch.Cross-project validation. When a feature branch is ready for review, CI triggers downstream validation: the main repo's test suite is run against the proposed schema. If tests fail, the schema change either needs adjustment or the main repo needs a corresponding update, coordinated via a linked PR.
Review and approval. The PR from the feature branch to main requires approval from at least one member of the calm-schema-governance group. Review considers correctness, backward compatibility, downstream impact, and alignment with the project's direction.
Release. When a schema change is merged to main, the package is published to npm with the new version number and a git tag is created. Releases use semantic versioning. Minor releases (backward-compatible additions) can be proposed at any time. Major releases (breaking changes) require a migration guide and coordination with the main repo maintainers.
What this replaces. The draft and releases folder structure in the existing monorepo is retired. The schema is edited in place on feature branches — there is no need to copy the current version into a new folder before making changes. Previous versions are preserved as git tags and npm registry releases, not as folders in the repository.
Release Process
calm-schema
calm-schema has a single package and a single versioning stream. Each release is tagged (e.g.,
v1.2.0) and a corresponding GitHub Release is created. Previous versions are available via npm and git tags.Main repository (multiple projects, independent releases)
The main repository contains multiple projects that release independently. Each project has its own versioning stream and its own GitHub Releases.
Consistent major version, independent minor and patch versions. All projects within the repository share a consistent major version but release minor and patch versions independently as changes are ready. For example, at a point in time the projects might have:
The shared major version (
2.x.x) signals compatibility: all projects at major version 2 are designed to work together and target the same major version of their upstream dependencies (calm-schema and any shared libraries within the repo). Individual projects ship features and fixes at their own pace.Major version bumps are coordinated across all projects in the repository simultaneously. A major version increment signals a breaking change — for example, a new calm-schema major version that requires changes across multiple projects, or a breaking change in a shared library. Major version bumps are proposed by the Project Maintainers and require agreement across the maintainer group before release.
Minor and patch releases are managed by the maintainers of the individual project. A minor release adds backward-compatible functionality; a patch release fixes a bug. These do not require coordination beyond the normal PR review process.
Git Tags and GitHub Releases in a Multi-Project Repo
Because a single repository hosts multiple independently-released projects, git tags and GitHub Releases are prefixed with the project name to disambiguate them. This is the standard approach used by mature multi-project repositories (Argo, Kubernetes SIGs, Lerna-based monorepos, and many others).
Tag format:
<project>/v<major>.<minor>.<patch>Examples:
Each tag maps to a GitHub Release with the same name. The GitHub Releases page for the repository shows all releases across all projects in a single feed, which makes it easy for users to see what has shipped recently. Filtering by tag prefix (e.g., searching for
calm-hub/) shows the release history for a specific project.Published package versions on npm and Maven Central follow standard semver without the prefix —
@finos/calm-cli@2.3.1, not@finos/calm-cli@calm-cli/v2.3.1. The prefix is only used for git tags and GitHub Release names, where it disambiguates one project's releases from another's within the same repository.Release notes. Each GitHub Release contains release notes for that project's changes only, scoped to commits that touched the project's directory. This is achieved through conventional commit scopes (e.g.,
feat(calm-hub): add authentication) combined with tooling that filters changelogs by scope.Release workflow. Releases are triggered by creating a prefixed tag. CI detects the tag prefix, builds the corresponding project, runs the test suite, publishes the package to the appropriate registry (npm for TypeScript, Maven Central for Java), and creates the GitHub Release with auto-generated release notes. Tooling such as
semantic-release-monorepoorchangesetsautomates this workflow; the choice of tool is a repository-level decision for the maintainers.Schema Version Adoption
When calm-schema publishes a new version, the main repository adopts it through a PR that updates the pinned
@finos/calm-schemaversion and makes any necessary adjustments to the CLI, shared libraries, or data models. This is a deliberate, reviewed update rather than an automatic side-effect. Renovate or Dependabot can raise the PR; the maintainers decide when to merge it.For minor and patch schema releases (backward-compatible), adoption happens when convenient. For major schema releases (breaking changes), adoption is coordinated with a corresponding major version bump across all projects in the main repository.
Governance
Single Project, Single Governance
All three repositories operate under a single governance structure defined in calm-governance.
Roles
Lead Maintainer. The project's interface with the FINOS team and board. Responsible for approving quarterly project reports and representing the project externally. Elected by the Project Maintainer group.
Project Maintainers. The senior maintainer group responsible for the overall direction of the project. Project Maintainers have merge authority across all repositories and are responsible for cross-cutting decisions including schema changes, new sub-project admission, and governance amendments.
Repository Maintainers. Contributors who have been granted merge authority over a specific repository. Repository Maintainers manage the day-to-day development of their repository: reviewing PRs, managing releases, and setting the roadmap within the bounds established by the Project Maintainers.
Contributors. Anyone who submits a contribution to any repository. Contributors follow the standard FINOS contribution process (CLA, PR review, conventional commits).
Becoming a Repository Maintainer
Contributors earn Repository Maintainer status through sustained, quality contribution to a specific repository.
calm-schema. Schema maintainers must demonstrate a deep understanding of the CALM specification, JSON Schema, and the impact of schema changes on downstream tooling. Candidates are expected to have authored or substantially contributed to multiple schema change proposals, participated in schema reviews, and shown good judgement on backward compatibility. Nomination is by an existing calm-schema maintainer or Project Maintainer, with approval by the calm-schema-governance group.
Main repository (calm). Maintainers must demonstrate sustained contribution to one or more projects within the repository. Candidates are expected to have a track record of merged PRs, participation in code review and issue triage, and an understanding of how their project relates to the other tools in the repository. Nomination is by an existing maintainer or Project Maintainer, with approval by the main repo maintainer group.
In all cases, the nominator should open an issue in calm-governance citing the candidate's contribution history. The relevant maintainer group reviews and approves by consensus.
Becoming a Project Maintainer
Repository Maintainers may be nominated for Project Maintainer status by an existing Project Maintainer. Promotion reflects contribution and commitment beyond a single repository — candidates are expected to have demonstrated sustained contribution across the project, good judgement on cross-cutting concerns, and alignment with the project's overall direction. Approval is by consensus of the existing Project Maintainers.
This is the standard open source meritocratic model: authority is earned through contribution over time.
Decision Making
Day-to-day decisions within a repository are made by that repository's maintainers. Cross-cutting decisions — including schema changes, new repository creation, and governance changes — are made by the Project Maintainers, seeking consensus with a simple majority vote as fallback.
Schema changes follow the feature-branch process described above: proposal via issue, development on a feature branch with CI validation, cross-project testing, and approval by the calm-schema-governance group.
Code Ownership
The main repository uses a
CODEOWNERSfile to ensure that changes to specific projects require review from the maintainers with subject matter expertise. CODEOWNERS maps each project directory to the maintainers responsible for it — changes tocli/require approval from the CLI maintainers, changes tocalm-guard/require approval from the CALM Guard maintainers, and so on.This ensures every PR is reviewed by someone with deep knowledge of the affected code, regardless of who submits it. A contribution to CALM Hub from a CALM Studio developer still requires sign-off from a CALM Hub maintainer. It also enables fine-grained oversight within a monorepo without fragmenting the repository itself — projects share a codebase and build infrastructure, but each has designated reviewers accountable for its quality and direction.
CODEOWNERS is enforced via GitHub branch protection rules. PRs cannot be merged without approval from the designated owners for all affected paths. The CODEOWNERS file is itself owned by the Project Maintainers.
GitHub Teams
The governance roles and code ownership model are implemented through GitHub Teams within the
finosorganisation.Project-level teams:
calm-project-maintainerscalm-schema-governanceRepository-level teams:
calm-schema-maintainerscalm-maintainersCODEOWNERS teams (per-project within the main repository):
calm-cli-owners/cli/,/server/calm-shared-owners/shared/,/calm-models/,/calm-widgets/calm-ai-owners/calm-ai/calm-hub-owners/calm-hub/,/calm-hub-ui/calm-vscode-owners/calm-vscode/calm-studio-owners/calm-studio/calm-guard-owners/calm-guard/,/calm-learning/calm-docs-owners/docs/A contributor may be a member of multiple teams. Project Maintainers are automatically members of all repository-level teams.
CODEOWNERS teams are intentionally granular. A PR that touches both
calm-hub/andcalm-studio/requires approval from bothcalm-hub-ownersandcalm-studio-owners, ensuring cross-project changes are reviewed by the relevant subject matter experts.Team membership is managed by the
calm-project-maintainersteam. Changes to team membership should be reflected in an issue in calm-governance for transparency.Meetings
The existing monthly community meetup and weekly Office Hours continue to cover the full project. All repositories are discussed in these forums. Working sessions can be scheduled as needed but are open to all project participants.
FINOS Reporting
All three repositories are registered under the CALM FINOS project. Contributor metrics from all repos roll up into a single project dashboard, supporting the path to Graduated status. Contributors from Sonatype, ArchRails, and other organisations working on CALM Suite components count towards the multi-organisation contributor requirement.
The updated FINOS Project Lifecycle (March 2026) renamed the previous "Active" stage to "Graduated" and introduced regular TOC health reviews every six months for Incubating and Graduated projects. The restructure proposed here directly supports the Graduated acceptance requirements: clear governance documentation, multi-organisation contribution, and alignment with the OpenSSF Security Baseline at Maturity Level 3.
Migration Plan
Phase 1: Governance
Create the calm-governance repository under the finos GitHub organisation. Draft and agree the GOVERNANCE.md with all current maintainers. This must be approved before any structural changes to code repositories.
Phase 2: Schema Extraction
Create the calm-schema repository under the finos GitHub organisation. Migrate the current released schema files (without version folders — the schema is edited in place), along with validation tests and examples. Existing drafts are converted to feature branches. Establish the feature-branch workflow, CI pipeline, and npm publishing. Tag and publish the current schema as the initial
@finos/calm-schemarelease, and publish previous schema releases to npm so the full version history is available in the registry.Phase 3: Main Repository Updates
Update the existing monorepo:
@finos/calm-schemanpm registry rather than referencing local files.calm-plugins/vscodetocalm-vscodeat the top level.<project>/v<major>.<minor>.<patch>) and adopt release tooling (e.g.,semantic-release-monorepoorchangesets).architecture-as-codetocalm.Phase 4: CALM Suite Integration
CALM Studio, CALM Guard, and CALM Learning are contributed into the main repository. The CALM Suite team are granted Repository Maintainer status for the main repo and added to the relevant CODEOWNERS teams.
Phase 5: FINOS Formalisation
Open a FINOS issue to formally record the Project Maintainers' endorsement of CALM Suite's inclusion. Update LFX reporting to ensure all three repositories are linked to the CALM project. Confirm with Morgan Stanley OSPO that the existing contribution approval covers the new repositories. Submit the project rebranding request to FINOS to update the project name from Architecture as Code to CALM across the FINOS landscape, registry, and reporting dashboards.
What This Structure Achieves
It welcomes CALM Suite into the project by embedding the incoming components directly in the existing codebase alongside the existing maintainers. It gives the schema a cleaner development workflow that eliminates the confusion of the current draft/releases folder approach. It establishes project-wide governance in a neutral, code-free location. It preserves the monorepo benefits of atomic cross-cutting changes, shared build infrastructure, and natural coordination between teams. It supports progression to FINOS Graduated status by aggregating all contributors under a single project and establishing the governance transparency that the TOC health review process requires. And it avoids premature restructuring — if the project grows to a scale where further splits are warranted, that decision can be made at that point, on evidence.