CONTRIBUTING.md

Contributing

How to add a new module or adjust existing ones.

Add a module

1. Create modules/<name>.md following the standard shape:

# Module: <name>

Active when `scope.<key> == "<value>"`.

## Deps
## Env vars
## Files
## Cross-integrations
## Docs

2. Add the question to AGENT.md in the right phase.
3. Add the key to the scope.json shape in AGENT.md.
4. If the module needs its own tests, create tests/<name>.yaml with an applies_when: that checks the scope key.
5. Add an entry to CHANGELOG.md under [Unreleased].

Conventions

• Install commands use pnpm.
• Never use process.env directly in examples — always go through src/lib/env.ts.
• The env vars listed must also appear in the generated project's src/lib/env.ts.
• Code examples must compile on the stack described in SPEC.md.
• Keep modules ≤ ~100 lines. If a module is bigger, it's probably two.

Cross-validations

If your module depends on another (e.g. usage-tracking needs auth + db), document it in:

• The module's "Cross-integrations" section
• The "Cross-validations" section in AGENT.md

Tests

Tests in tests/*.yaml are contracts. Prefer:

• File-exists checks (cheap, fast)
• HTTP checks against the dev server (realistic)
• Grep checks on code when a pattern is mandatory (e.g. constructEvent in the Stripe webhook)

Avoid tests that require real credentials unless marked requires_env: true.