stack-constraints

name	stack-constraints
description	Stack version pinning and dependency compatibility guards. Prevents silent version drift across project boundaries.

Stack Constraints

Rules for managing dependency versions and technology choices across all project types.

Version Pinning Policy

When starting a new project, prefer stable, well-documented versions over bleeding-edge:

• ORM / database tools — use latest stable, not pre-release (e.g., avoid beta/canary/rc).
• Framework — use LTS or latest stable release.
• Language runtime — use latest stable (not beta/rc).
• UI libraries — use latest stable release.

Check package documentation for "stable" vs "experimental" badges before adopting.

Dependency Installation Protocol

When agents create code requiring new packages:

1. Agents should install dependencies as part of their task — if they have Bash permission, they must install what they import.
2. If an agent lacks permission, pause and instruct the user to install manually before continuing.
3. Always test the build after new dependencies — run the dev server, not just the type checker. Static analysis doesn't catch missing runtime packages.
4. Check for peer dependency warnings — these often surface as runtime crashes, not compile errors.

When to Downgrade

Downgrade from a newer version to a stable one when:

• CLI or build tooling breaks (common with major version bumps of ORMs, bundlers, and frameworks).
• Runtime behavior changes unexpectedly from documented behavior.
• Community plugins/extensions don't yet support the new version.
• Error messages reference features marked "experimental" or "early access."

Document the version pin and the reason in the project CLAUDE.md or a DECISIONS.md so future contributors know why.

Stack-Specific Notes

Add version constraints relevant to your project in the project-level CLAUDE.md. For example:

## Stack Constraints
- ORM: Prisma 6.x (7.x has breaking CLI changes as of Feb 2026)
- Runtime: Node 20 LTS (not 22 — some deps don't support it yet)
- Framework: Next.js 14 stable (not 15 canary)

This keeps global rules generic while allowing each project to pin its own versions.