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)
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
just dev-runuses shared services when running, falls back to local sidecars otherwiseWorktree lifecycle (worktrunk integration)
.config/wt.tomlhooks: copy caches (reflink), install deps, re-tag Docker images, assign deterministic portshash_portfor deterministic port assignment (10000-19999 range, derived from branch name).dev-portfile read byjust dev-run— no manual port argument neededJustfile recipes (30+)
dev-runwith port/image/mode resolution,dev-stop,dev-restart,dev-waitdev-shared-start/stop/status/cleanand per-worktree cleanupdev-start-frontendwith parallel worktree supportbuild-quickerwith.m2WAR staleness detectionworktree-initfor warm-start new worktreesLefthook git hooks (replacing Husky)
Agent context restructuring
.claude/rules/for path-scoped loading (Java, Maven, frontend, test, E2E, shell, docs, CI/CD)justaliasesdotcms-dev-servicesanddotcms-worktreefor on-demand workflow guidanceCLAUDE.mdconverted to symlink →AGENTS.mdfor cross-agent compatibilityContext architecture guide
docs/claude/CONTEXT_ARCHITECTURE.md— tool-agnostic decision framework for structuring AI agent instructionsEvolution from Original Issue
The original approach proposed
.mvn/maven.configper worktree for image tag isolation. The implementation evolved to usejustaliases 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-runworks immediately afterwt switch --createwith 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-runresolves port, image, and mode per worktree without manual configurationjust dev-shared-startlaunches shared DB + OpenSearch usable by all worktreeswt switch --createproduces a warm-start worktree ready forjust devhash_port— same branch always gets same portjust build-quickerdetects and warns when.m2WAR is from another branch.claude/rules/provides Claude Code parity with existing.cursor/rules/