feat(dx): development environment setup — shared services, worktree integration, agent context architecture

Summary

Comprehensive developer experience improvements for the dotCMS monorepo, enabling parallel worktree development with shared infrastructure and optimized AI agent context.

PR: #34767

What Changed

Shared services for parallel worktrees

• Docker Compose stack (PostgreSQL + OpenSearch 1.3 + 3.4) shared across worktrees — saves ~4GB RAM per additional worktree
• Per-worktree database and OpenSearch index isolation via naming conventions
• Auto-detection: just dev-run uses shared services when running, falls back to local sidecars otherwise

Worktree lifecycle (worktrunk integration)

• .config/wt.toml hooks: copy caches (reflink), install deps, re-tag Docker images, assign deterministic ports
• hash_port for deterministic port assignment (10000-19999 range, derived from branch name)
• Pre-remove/post-remove hooks for container cleanup
• .dev-port file read by just dev-run — no manual port argument needed

Justfile recipes (30+)

• dev-run with port/image/mode resolution, dev-stop, dev-restart, dev-wait
• dev-shared-start/stop/status/clean and per-worktree cleanup
• dev-start-frontend with parallel worktree support
• build-quicker with .m2 WAR staleness detection
• worktree-init for warm-start new worktrees

Lefthook git hooks (replacing Husky)

• Pre-commit: frontend lint + format (staged files only)
• Pre-push: Java compile check, OpenAPI freshness, frontend format verify

Agent context restructuring

• Root AGENTS.md slimmed from 132 to 79 lines — domain-specific content moved to path-scoped rules
• 8 new .claude/rules/ for path-scoped loading (Java, Maven, frontend, test, E2E, shell, docs, CI/CD)
• Cursor rules updated: raw Maven commands replaced with just aliases
• Skills: dotcms-dev-services and dotcms-worktree for on-demand workflow guidance
• CLAUDE.md converted to symlink → AGENTS.md for cross-agent compatibility

Context architecture guide

• docs/claude/CONTEXT_ARCHITECTURE.md — tool-agnostic decision framework for structuring AI agent instructions
• Covers: command aliases as abstraction, five context layers, anti-patterns, tool-specific appendices

Evolution from Original Issue

The original approach proposed .mvn/maven.config per worktree for image tag isolation. The implementation evolved to use just aliases that handle the isolation internally (worktree-specific container names, image tags, and volume names) without requiring per-worktree Maven config files. This is simpler for developers — just dev-run works immediately after wt switch --create with no manual setup.

The scope expanded to include shared services (original issue only covered isolation, not resource sharing), frontend dev server support, lefthook git hooks, and a complete agent context architecture.

Acceptance Criteria (Updated)

• just dev-run resolves port, image, and mode per worktree without manual configuration
• just dev-shared-start launches shared DB + OpenSearch usable by all worktrees
• Per-worktree database and OpenSearch index isolation in shared mode
• wt switch --create produces a warm-start worktree ready for just dev
• Deterministic port assignment via hash_port — same branch always gets same port
• just build-quicker detects and warns when .m2 WAR is from another branch
• Lefthook hooks replace Husky for pre-commit and pre-push checks
• Root AGENTS.md under 100 lines with path-scoped rules for domain-specific context
• .claude/rules/ provides Claude Code parity with existing .cursor/rules/
• Context architecture guide documents the decision framework

Start with PR #34767, then inspect the referenced Justfile, .config/wt.toml, AGENTS.md, .claude/rules/, and docs/claude/CONTEXT_ARCHITECTURE.md. Compare the implementation with the checked acceptance criteria, including shared services, worktree setup, hooks, and agent-context restructuring; the listed criteria define done.