Contributing to AlignTrue

Thank you for your interest in contributing to AlignTrue! We welcome contributions from everyone: whether you’re creating Aligns, improving documentation, adding exporters, or fixing bugs in the core codebase.

Contribution types

AlignTrue has many ways to get involved:

Content contributions

Create and maintain rule sets (Aligns) that help others align their AI agents.

Create Aligns — Write rules that solve real problems for your domain or stack.

Edit documentation — Improve docs on the site or contribute to our docs-first architecture.

Code contributions

Extend AlignTrue’s core platform and integrations.

Add exporters — Support new AI agents and platforms.

Development setup — Local environment, build, and test workflow.

Getting started

1. New to contributing? Start with How to contribute.
2. Unsure what to work on? Check GitHub Issues  for good-first-issue labels.
3. Want to discuss first? Join GitHub Discussions .

Key workflows

Before you start

• Review the Code of Conduct below
• Check Development setup to get your environment ready
• Read Testing workflow — all contributions need tests

While working

• Create a feature branch
• Write tests alongside your changes
• Follow the relevant guide (Aligns, docs, exporters)
• Keep a fast loop running: pnpm test:fast

Before submitting a PR

1. Run the workspace checks: pnpm check
2. Mirror CI locally: pnpm pre-ci
3. Update CHANGELOG.md if needed
4. Open a GitHub Draft PR with a clear description of what changed and why

Code of conduct

We aim to build a welcoming, constructive community:

• Be respectful — Treat all contributors with respect and consideration
• Be constructive — Focus on improving the quality of work, not criticizing people
• Be objective — Ground discussions in concrete examples and data
• Be clear — Explain your reasoning when proposing or reviewing changes

We have zero tolerance for harassment, discrimination, or hostile behavior.

Common questions

I want to contribute but don’t know what to work on

• Browse GitHub Issues  and filter by good-first-issue
• Check GitHub Issues  for accepted ideas
• Ask in GitHub Discussions 

What if my work is incomplete?

• Open a GitHub Draft PR (no [WIP] prefix needed)
• Push your branch frequently so reviewers can follow along
• Describe what’s done and what’s left
• We’re happy to provide feedback before completion

How long does review take?

• Small PRs (< 200 lines): 1-3 days
• Medium PRs: 3-5 days
• Large changes: We may request phased submission to keep reviews manageable
• If you have not heard back in 3 business days, feel free to add a gentle ping

Can I work on this issue?

• Comment on the issue to claim it; maintainers will confirm or suggest next steps
• If an accepted, unassigned issue has no response after 3 business days, you can proceed and note that you’re taking it
• Some issues are reserved for maintainers — they’ll be labeled

Learning resources

Documentation

• Getting started
• How AlignTrue works — Core concepts and architecture
• Development guide
• Architecture

Code references

• Schema validation 
• CLI commands 
• Core library 
• Exporters 

Examples

• examples/aligns/README.md — ready-to-use rule sets and authoring patterns
• examples/golden-repo — end-to-end baseline repo with overlays scenarios
• examples/overlays-demo — focused overlays walkthrough

Getting help

Stuck or need guidance?

• Issues: GitHub Issues  — Report bugs or ask for features
• Discussions: GitHub Discussions  — Ask questions, share ideas
• Documentation: Full docs — Search for concepts or commands
• Development guide: Setup and workflow

Contribution checklist

Before submitting:

• I have read the Code of Conduct
• I have reviewed the relevant contribution guide
• I have tested my changes locally
• I have added tests for new functionality
• I have updated documentation (if needed)
• I have updated CHANGELOG.md (for user-facing changes)
• All checks pass: pnpm check
• All pre-CI checks pass: pnpm pre-ci

Thank you for helping make AlignTrue better for everyone!