Contributing Taxonomies

Mandaitor is designed to grow through community input, but the taxonomy layer is curated carefully so that growth does not create semantic drift, duplicate labels, or unsafe delegation defaults. This page explains how contributions work, what maintainers review, and how a merged contribution eventually becomes part of the live Mandaitor system.

Where Contributions Happen

Community taxonomy work starts in the public mandaitor-taxonomies repository. Contributors can either open a proposal issue for a new vertical or submit a direct pull request when the scope is already clear.

Entry path	Best used for	Outcome
Proposal issue	New verticals, major restructuring, uncertain naming	Early maintainer alignment before implementation
Direct pull request	Well-scoped additions, refinements, documentation changes	Immediate review through normal contribution flow

Contribution Lifecycle

A contribution moves through several stages before it appears in the live Mandaitor ecosystem.

Stage	What happens	Decision owner
Community proposal	A contributor discusses or implements a change	Community initiates
Pull request	The contribution is submitted to mandaitor-taxonomies	Community submits
Automated validation	Build, test, and validation workflows run	Automation
Curation review	Naming, scope, overlap, risk, and metadata are reviewed	Mandaitor maintainer
Merge to source	The change becomes part of the public taxonomy repository	Mandaitor maintainer
Release publication	The package is versioned and published	Mandaitor maintainer
Downstream import	Automation proposes the released package to mandaitor-core	Automation
System adoption	The downstream import PR is reviewed and merged	Mandaitor maintainer

A merged PR in mandaitor-taxonomies means the contribution has been accepted into the public source of truth. It becomes part of the live Mandaitor system only after downstream release and import are also approved.

What a Good Contribution Contains

A useful taxonomy contribution increases precision rather than just adding more vocabulary. Contributors should aim to make the model clearer, not noisier.

Element	What to provide
Identity	Stable IDs, clear labels, concise descriptions
Scope	Resource boundaries, intended use cases, non-goals
Safety	Risk classification and human approval expectations
Governance	Maturity state and deprecation intent where relevant
Context	Related concepts, standards, examples, jurisdictional notes

For the detailed field guide, see the repository schema reference at docs/taxonomy-schema.md.

Maturity Model

Mandaitor distinguishes between the maturity of a concept and the fact that it exists in a repository. Contributors should state the intended maturity of new entries or substantial refinements.

Maturity	Meaning	Expected maintainer posture
draft	Early idea still being shaped	Discussion encouraged, not yet canonical
candidate	Well-formed and reviewable	Good merge candidate if quality is high
stable	Reviewed and suitable as canonical terminology	Safe basis for downstream adoption
deprecated	Kept only for compatibility or migration	Should not be used for new designs

Contribution Types

Not every contribution is a brand-new taxonomy. Contributors should clarify what kind of change they are making.

Contribution type	Typical example
New entry	Add a new action, template, or governed term
Refinement	Improve an existing label, description, or hierarchy
Alias	Add a discoverability synonym without duplicating semantics
Relationship	Add parent-child or related-term linkage
Deprecation	Retire an ambiguous term in favor of a clearer successor

Design Principles

The taxonomy layer exists to make AI delegation trustworthy, reviewable, and operable at scale. That requires discipline in how concepts are named and grouped.

Principle	Interpretation
Least privilege	Prefer narrow actions and resource scopes over broad permissions
Granularity over breadth	Many precise actions are better than one vague omnibus action
Real-world mapping	Concepts should correspond to recognizable business operations
Safety by default	High-impact actions require clear approval and escalation semantics
Semantic stability	Names should still make sense after multiple releases

How to Start

1. Fork the mandaitor-taxonomies repository.
2. Install dependencies with pnpm install.
3. Create a branch for your contribution.
4. Scaffold or edit the target taxonomy.
5. Run pnpm build, pnpm test, and pnpm validate.
6. Open a pull request and complete the repository template fully.
7. Follow the maintainer review and release path.

For the repository-level contributor instructions, see CONTRIBUTING.md in the taxonomy repository.