Contributing

Tahyi is being built for self-hosted deployment (MIT-licensed when publicly released). Contributions — code, documentation, issues, and design feedback — will open once the scaffold ships and the board approves public repo visibility (TAH-77).

This page covers how to contribute effectively. For the execution model you’ll be working inside, see How it Works.

Before you start

Read the mission and scope — MISSION and SCOPE define what Tahyi is and what 1.0 includes.
Skim Core Concepts — understand swarm, specialists, two-way/one-way doors, and the coordination layer before touching code.
Check open issues — avoid duplicating work. Link your PR to an existing issue when one exists.

Documentation-first

Tahyi follows documentation-first (P1): if a decision or behavior isn’t written down, it doesn’t exist. When you change code:

Update the relevant doc page in the same PR
Match front-matter schema (see INTEGRATION.md attachment)
Use canonical terminology: two-way door / one-way door (not “Speed-1” / “Speed-2”)

Docs live in content/ within the site repo. Voice: professional, technical, direct — developer audience.

Code contributions

Repos are private during pre-release (TAH-87). When the board approves public release:

git clone https://github.com/kay-g2/tahyi.git
cd tahyi
npm install
npm test

Workflow

Open an issue first for non-trivial changes — describe the problem, proposed approach, and affected specialist domain.
Fork and branch — use descriptive branch names (fix/deployment-dry-run, docs/how-it-works-examples).
Keep PRs focused — one concern per PR. Large changes should be discussed in an issue before coding.
Run tests locally — CI must pass before merge.
Link the issue — PR description references the issue it closes or relates to.

Specialist domains

Match your contribution to the right domain:

Domain	Specialist	Examples
Deployment	`deployment-maintainer`	Rollout logic, rollback, pipeline integration
Monitoring	`monitoring-maintainer`	Alert routing, SLO evaluation
Observability	`observability-maintainer`	Log/metric/trace correlation
DBA	`dba-maintainer`	Migrations, backups, query analysis
Coordination	Core layer	Task routing, safety gates, audit log

Cross-cutting changes (coordination layer, safety model) need extra review — they affect every specialist.

Docs contributions

Docs are Markdown with YAML front-matter. No custom components in v1 — plain Markdown only.

---
title: Page Title
description: One-line summary for nav and meta.
section: learn | reference
category: null
order: 10
draft: false
---

Diátaxis guide:

Learn section — tutorials, how-tos, explanations (this page, Quickstart, Core Concepts)
Reference section — architecture, agent catalog, configuration keys

See Branding Kit v1 for typography and voice.

Reporting bugs

Include:

Tahyi version (npx tahyi --version)
Environment type (kubernetes, etc.)
Specialist involved
Steps to reproduce
Relevant audit log excerpt (redact secrets)

Security

Do not open issues for security vulnerabilities until public release channels exist. Use the security contact in the repo’s SECURITY.md (added with the public scaffold).

Never commit secrets, API keys, or credentials. Tahyi uses environment-injected credentials only.

Code of conduct

The project follows a standard code of conduct (included in the repo root when publicly released). Be direct, be respectful, assume good intent.

Getting help

GitHub Discussions — questions and ideas (when live)
Issues — bugs and feature requests
Project thread — TAH-74 for company-level updates during pre-release