Skip to Content
06 ContributingCreating packs

Creating packs

Thank you for your interest in contributing to AlignTrue! This guide will help you create high-quality Align packs that pass validation and provide value to the community.

Quick start

Get started creating packs:

  1. Review examples in the examples/packs/ directory
  2. Create your pack following the template
  3. Share via GitHub URL, local file, or your own repository

No central registry exists - share packs however works best for your team.

Authoring your first pack

Review examples

Browse example packs in examples/packs/ in this repository.

Examples include:

  • Base packs (global, testing, security, etc.)
  • Stack-specific packs (Next.js, Vercel, etc.)
  • Inline comments explaining best practices
  • Proper pack structure and formatting

Choose your namespace

Pick the appropriate namespace for your pack:

  • packs/base/* - Rules that apply across all stacks

    • Example: packs/base/base-testing, packs/base/base-security
    • Use when: Your rules work for any project type

  • packs/stacks/* - Rules specific to a framework or stack

    • Example: packs/stacks/nextjs-app-router, packs/stacks/django-backend
    • Use when: Your rules target a specific tech stack

See POLICY.md for complete namespacing rules.

Minimal example

Here’s a minimal Align pack with one rule:

id: "packs/base/base-example"
version: "1.0.0"
profile: "align"
spec_version: "1"
summary: "Ensure all TypeScript projects have proper configuration"
tags: ["typescript", "configuration"]
deps: []
 
scope:
  applies_to: ["backend", "frontend"]
 
rules:
  - id: require-tsconfig
    severity: MUST
    check:
      type: file_presence
      inputs:
        pattern: "tsconfig.json"
        must_exist: true
      evidence: "TypeScript project missing tsconfig.json"
    autofix:
      hint: "Run `npx tsc --init` to create tsconfig.json"
 
integrity:
  algo: "jcs-sha256"
  value: "<computed>"

For more examples, browse existing packs in the examples/packs/ directory.

Testing locally

Prerequisites

You’ll need:

  • Node.js 22+ and pnpm 9+
  • The AlignTrue/aligntrue repository cloned

Validate your pack

From the aligntrue repository:

# Install dependencies
pnpm install
 
# Validate your pack
pnpm --filter @aligntrue/schema validate path/to/your-pack.yaml

Verify deterministic hash

Run validation twice and confirm the integrity hash is identical both times:

pnpm --filter @aligntrue/schema validate path/to/your-pack.yaml
# Note the integrity hash in output
 
pnpm --filter @aligntrue/schema validate path/to/your-pack.yaml
# Hash should match exactly

If hashes differ, your pack may have non-deterministic content (timestamps, random values, etc.).

Compute integrity hash

If your pack has <computed> as the integrity value, compute the real hash:

# From the aligntrue repository
pnpm --filter @aligntrue/schema compute-hash path/to/your-pack.yaml

Copy the hash from the output and paste it into your pack’s integrity.value field.

Machine-checkable rules

All rules in AlignTrue must be machine-checkable. No vibes, no subjective judgments.

The 5 check types

Every rule must use one of these check types:

  1. file_presence - Check if files exist or don’t exist

    check:
  type: file_presence
  inputs:
    pattern: "README.md"
    must_exist: true

  2. path_convention - Validate file paths match patterns

    check:
  type: path_convention
  inputs:
    pattern: "src/**/*.test.{ts,tsx}"
    convention: "kebab-case"

  3. manifest_policy - Check package.json or lockfile constraints

    check:
  type: manifest_policy
  inputs:
    manifest: "package.json"
    lockfile: "pnpm-lock.yaml"
    require_pinned: true

  4. regex - Pattern matching in file contents

    check:
  type: regex
  inputs:
    include: ["**/*.ts"]
    pattern: "\\bconsole\\.log\\("
    allow: false

  5. command_runner - Execute commands and check exit codes

    check:
  type: command_runner
  inputs:
    command: "pnpm typecheck"
    expect_exit_code: 0

See the checks documentation for complete details on each type.

Evidence messages

Evidence messages must be actionable and specific:

  • Bad: “Validation failed”

  • Good: “Missing test file for src/utils/parser.ts”

  • Bad: “Fix your configuration”

  • Good: “tsconfig.json missing ‘strict: true’ in compilerOptions”

Include file names, line numbers, or specific missing values when available.

Autofix hints

When you provide an autofix hint, make it concrete:

  • Bad: “Add tests”

  • Good: “Run pnpm test --init src/utils/parser.test.ts”

  • Bad: “Use a logger”

  • Good: “Replace with logger.debug() or remove the statement”

Users should be able to copy-paste your hint and make progress.

Choose the right severity

  • MUST: Blocking issues that break builds or cause errors

    • Uninstalled imports
    • Missing required configuration
    • Security vulnerabilities

  • SHOULD: Warnings about problems that don’t block

    • Missing tests
    • Incomplete documentation
    • Deprecated patterns

  • MAY: Suggestions and style preferences

    • console.log statements
    • TODO comments
    • Formatting preferences

See POLICY.md for complete severity guidelines.

Sharing your pack

Via GitHub

  1. Publish to GitHub - Users can import via git URLs:
sources:
  - type: git
    url: https://github.com/yourorg/rules-repo
    path: packs/your-pack.yaml
  1. Share raw URL - Users can download directly:
curl -o .aligntrue/rules.yaml https://raw.githubusercontent.com/yourorg/rules-repo/main/packs/your-pack.yaml

Via local files

Share the YAML file directly - users can copy it to their project:

cp your-pack.yaml .aligntrue/rules.yaml
aligntrue sync

Quality checklist

Before sharing your pack, verify:

  • Schema validation passes locally
  • Integrity hash is computed (not <computed>)
  • Evidence messages are specific and actionable
  • Autofix hints are concrete commands or steps
  • Pack summary clearly states purpose in one sentence
  • Namespace follows conventions (packs/base or packs/stacks)
  • All check types use one of the 5 supported types

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 rules, not criticizing authors
  • 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.

Getting help

Stuck? Here’s how to get help:

Sharing with the community

Consider sharing your pack with the community:

  1. GitHub repository - Create a public repo with your packs
  2. Documentation - Add a README explaining what your packs do
  3. Examples - Include usage examples and configuration
  4. Community - Share in GitHub Discussions 

Well-documented packs help others learn and adopt best practices.

Advanced topics

Dependencies between packs

Packs can depend on other packs using the deps field:

deps:
  - id: "packs/base/base-global"
    version: "^1.0.0"

Dependencies are resolved and merged in order. Keep dependencies minimal.

Scoping rules

Use scope.applies_to to narrow where your pack applies:

scope:
  applies_to: ["backend"] # or ["frontend"], ["cli"], etc.

This helps users understand when to use your pack.

Testing check runners

You can test check runners locally with:

# From the aligntrue repository
pnpm --filter @aligntrue/checks run-checks ../aligns/packs/base/your-pack.aligntrue.yaml /path/to/test/repo

This runs your checks against a test repository and shows findings.

Questions?

If this guide doesn’t answer your question:

We’re here to help!

Thank you for contributing to AlignTrue and helping make AI-human alignment better for everyone.

Last updated on
Extending AlignTrueEditing documentation