docs: AGENTS.md improvements validated by agent test suite by spbolton · Pull Request #34767 · dotCMS/core

spbolton · 2026-02-25T13:23:30Z

Summary

Add symlink note to AGENTS.md clarifying CLAUDE.md → AGENTS.md (Claude Code reads CLAUDE.md; Codex/Aider/Cursor read AGENTS.md — same content)
Add build scope heuristic — guides agents to choose just build-quicker for core-only changes vs full rebuild, eliminating the most common over-building antipattern
Add REST patterns breadcrumb — points agents to docs/backend/REST_API_PATTERNS.md with a warning that generic JAX-RS patterns are insufficient for dotCMS endpoints
Add design and implementation plan docs for the agent test suite that validated these changes

Motivation

An agent test suite (~/.claude/skills/dotcms-agent-tests/) was built to validate progressive context gathering from AGENTS.md alone. Baseline tests showed:

BE-003 (add REST endpoint): 3/10 — no path from AGENTS.md to REST patterns docs
BE-002 (build selection): 7/10 marginal — missing decision heuristic for scope selection

After applying these changes, all 4 test scenarios passed (40/40).

Scope

This PR contains documentation and AI context file changes (AGENTS.md, docs/, cursor rules, worktrunk config). The key additions in this review cycle are the three AGENTS.md improvements and docs/plans/ files.

Test plan

Review AGENTS.md diff — three additions: symlink note, build heuristic, REST breadcrumb
Review docs/plans/2026-02-26-dotcms-agent-tests-*.md — design and impl docs
Confirm no production code changes included

🤖 Generated with Claude Code

cursor · 2026-02-25T13:23:34Z

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

…er requirement

… path bug

…chas only

AGENTS.md (82 lines): build/test/run commands, critical rules, doc navigation table, Cloud VM gotchas. References /docs/ for all detailed patterns instead of duplicating. CLAUDE.md (7 lines): thin redirect for Claude Code compatibility.

- Root AGENTS.md trimmed to 51 lines: build/test/run, references, Cloud VM - Removed duplicated rules (Config/Logger, Maven versions, Angular syntax, commits, branches) — already in .cursor/rules/ and /docs/ - Removed tech stack section — discoverable from project files - Removed doc navigation table — docs/README.md serves this purpose - Updated dotcms-guide.mdc to reference AGENTS.md instead of CLAUDE.md - Removed duplicated critical reminders from dotcms-guide.mdc Progressive disclosure layers: 1. AGENTS.md (every request): how to build/run, where to find docs 2. .cursor/rules/ (file-pattern): domain rules for the task at hand 3. /docs/ (on-demand): detailed patterns and examples

- core-web/CLAUDE.md: replaced 267-line file with 70-line gotcha-focused guide. Removed hardcoded Angular 19.2.9, Nx 20.5.1 versions (were actually 20.3.16, 21.6.9). Replaced with 'check package.json'. - core-web/nx-rules.mdc: removed hardcoded Nx 20.5.1 version - frontend-context.mdc: removed hardcoded Angular 20+ version - docs/README.md: reference AGENTS.md instead of CLAUDE.md - java-context.mdc: already had Java 25 migration note (from earlier)

Standardize on AGENTS.md as the source file across the entire repo. Each CLAUDE.md becomes a symlink → AGENTS.md so Claude Code still finds its expected file. Affected directories: - core-web/ - test-jmeter/ - examples/nextjs/ - examples/angular-ssr/ - core-web/libs/sdk/react/ - core-web/libs/sdk/client/ - dotCMS/src/main/java/com/dotcms/rest/ - core-web/apps/mcp-server/

- post-create: auto-trust mise config (no-op if mise not installed) - post-start: copy frontend caches from base worktree to avoid cold starts - .worktreeinclude: scopes copy to node_modules, Nx, and Angular caches Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Prettier exits with error code 2 when encountering symlinks, causing the NX format:check step to fail. Remove all CLAUDE.md symlinks in subdirectories — AGENTS.md is the canonical file name everywhere. The root CLAUDE.md symlink is kept since there's no Prettier check at the repo root level.

Captures the architecture for validating AI agent progressive context gathering using worktrunk-isolated sub-agents and a review agent scorer. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Step-by-step plan covering skill creation, 4 test cases (BE-001/002/003, FE-001), RED/GREEN baseline runs, AGENTS.md gap fixes, and PR scope. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…eadcrumb Three conceptual improvements validated by agent test baseline (RED phase): - Clarify CLAUDE.md is a symlink to AGENTS.md for multi-agent compatibility - Add build scope heuristic: match scope to what changed, not safe = slow - Add REST_API_PATTERNS.md reference: dotCMS auth/response conventions differ from generic JAX-RS; agents need the signal to navigate there All changes are conceptual signals, not prescriptive commands, so they remain useful as the codebase evolves. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…etup-e028' into cursor/development-environment-setup-e028

Cursor Cloud setup details (vfs driver, iptables-legacy, dockerd startup) were loading on every prompt, polluting context for standard dev work and risking misleading agents on non-cloud environments. - Extract to docs/infrastructure/CURSOR_CLOUD_SETUP.md (load on demand) - Keep only universal gotchas: pre-commit hooks (SDKMAN), frontend OOM - Add reference breadcrumb so agents can navigate there when needed - Fix core-web reference from CLAUDE.md → AGENTS.md (symlink removed by CI fix)

Three gaps found by agent test suite (BE-004, BE-005, FE-002): - Fix port 8082 → 8080: frontend proxy hardcodes localhost:8080; using a different port breaks all API calls from the dev server - Add first-run note: build produces the Docker image the start command uses — agents were navigating to justfile to discover this connection - Add restart note: after a core rebuild, restart the stack to pick up the new image (dev-stop && dev-start) — not discoverable from AGENTS.md - Add frontend proxy note: nx serve proxies API to :8080, no backend rebuild needed for frontend-only changes - Update CURSOR_CLOUD_SETUP.md: flag proxy port dependency for cloud VMs using a non-default backend port

- Add justfile recipes: dev-health, dev-wait, dev-urls, _dotcms-container - Dynamic management port (8090) discovery from Docker — never hardcoded - Container discovery by image prefix (tag-agnostic, multi-worktree safe) - dev-start-on-port now prints access URLs on completion - dev-start-frontend discovers backend port from Docker and injects DOTCMS_HOST - dev-stop-frontend: lsof fallback chain (lsof → ss → fuser) for Linux portability - Rewrite build-quicker: filtered output (phase transitions + errors), full log in /tmp - Add .mvn/maven-build-cache-config.xml with cache disabled to prevent stale Docker layer SHAs - Update AGENTS.md: cross-platform requirement section, build visibility strategy, dynamic port guidance, agent log strategy, frontend proxy discovery note - Update core-web/AGENTS.md: dev-start-frontend lifecycle commands, :4200 vs :8080 gotcha - Add .frontend.pid to .gitignore Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Backend: - Add DemoResource.java: GET /api/v1/demo/greet returns greeting + uptimeSeconds - Add ResponseEntityDemoGreetingView.java view class - Register endpoint in openapi.yaml Frontend: - dot-toolbar.component.ts: fetch greeting/uptime on init via HttpClient signals - dot-toolbar.component.html: display '🟢 dotCMS is live up Xh Ym Zs' in toolbar - proxy-dev.conf.mjs: replace hardcoded :8080 target with process.env.DOTCMS_HOST (injected by just dev-start-frontend — falls back to :8080 if not set) Validates the full dev loop end-to-end: backend build → Docker image → server start → Angular dev server → live toolbar health display. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…docs - Apply same filtered output + /tmp log pattern to `just build` (was only in build-quicker). Both commands now show phase transitions, errors, and save full log for progressive deep-dive. - AGENTS.md build-visibility note: updated to say 'Both just build and just build-quicker' instead of only build-quicker. - AGENTS.md server-urls note: clarify that dev-start-on-port fixes the app port you specify, but management port is always dynamic. Make dev-urls the authoritative source for actual live URLs after any start or restart. - Fix misleading command comment: 'prints URLs on completion' → 'app on :8080' so it's clear the port argument fixes the app port, not all ports. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- dotCMS/pom.xml: set docker.filter to include dotcms app container so dev-stop stops the full stack, not just DB and OpenSearch sidecars - justfile: add name-pattern fallback to _dotcms-container and dev-start-frontend — handles post-rebuild case where Docker strips the named tag from the old container, breaking image-based discovery - justfile: add dev-restart recipe (stop all + start on port) - justfile: add dev-frontend-status (non-blocking tail -40 snapshot) - justfile: clarify dev-stop and dev-frontend-logs comments - AGENTS.md: add dev-restart and dev-frontend-status to command ref; update restart workflow note; clarify dev-stop stops all containers - core-web/AGENTS.md: fix stale "port 8080" proxy note; dev-start-frontend auto-discovers the backend port — direct nx serve falls back to 8080 only - docs/infrastructure/CURSOR_CLOUD_SETUP.md: fix stale instruction to manually edit proxy-dev.conf.mjs; use just dev-start-frontend instead Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fmontes · 2026-03-02T17:43:42Z

core-web/AGENTS.md

+npx nx serve dotcms-ui                    # dev server (:4200), proxies API to :8080
+
+npx nx test dotcms-ui                     # unit tests
+npx nx lint dotcms-ui                     # lint
+npx nx test dotcms-ui --testPathPattern=dot-edit-content  # single test file
+yarn run test:dotcms                      # all project tests
+yarn run lint:dotcms                      # all project lint
+npx nx affected -t test --exclude='tag:skip:test'         # changed projects only


why don't we standarize to yarn for all? instead of a combination of npx and yarn?

fmontes · 2026-03-04T17:40:49Z

core-web/apps/dotcms-ui/src/app/view/components/dot-toolbar/dot-toolbar.component.html

+            @if (serverGreeting()) {
+                <span class="text-sm px-2" style="color: var(--color-palette-primary-400)">
+                    🟢 <strong>{{ serverGreeting() }}</strong>
+                    <span class="text-xs ml-1" style="opacity: 0.7">{{ serverUptime() }}</span>
+                </span>


What is this for?

fmontes · 2026-03-04T17:41:26Z

core-web/apps/dotcms-ui/src/app/view/components/dot-toolbar/dot-toolbar.component.html

    <ng-template pTemplate="end">
        <div class="flex gap-1 align-items-center">
+            @if (serverGreeting()) {
+                <span class="text-sm px-2" style="color: var(--color-palette-primary-400)">


tailwind classes.

what is this form?

fmontes · 2026-03-04T17:41:37Z

core-web/apps/dotcms-ui/src/app/view/components/dot-toolbar/dot-toolbar.component.html

        <div class="flex gap-1 align-items-center">
+            @if (serverGreeting()) {
+                <span class="text-sm px-2" style="color: var(--color-palette-primary-400)">
+                    🟢 <strong>{{ serverGreeting() }}</strong>


primeng icon

fmontes · 2026-03-04T17:42:15Z

core-web/apps/dotcms-ui/proxy-dev.conf.mjs

+
+// Backend target: discovered at startup via DOTCMS_HOST env var (set by `just dev-start-frontend`).
+// Falls back to :8080 if not set — the conventional fixed port for `just dev-start-on-port 8080`.
+const target = process.env.DOTCMS_HOST || 'http://localhost:8080';


fmontes · 2026-03-05T23:03:42Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/demo/DemoResource.java

we have a /health one, we should fix that.

fmontes · 2026-03-05T23:06:53Z

AGENTS.md

+./mvnw install -DskipTests                        # full build (~8-15 min), or: just build
+./mvnw install -pl :dotcms-core -DskipTests        # core only (~2-3 min), or: just build-quicker
+
+just dev-start-on-port 8080                        # start stack (DB + OpenSearch + app) with app on :8080


Can't we just have one dev-start and the port is optional?

fmontes · 2026-03-05T23:07:46Z

AGENTS.md

+> **First run:** build first (`just build`), then start — the build produces the Docker image the start command uses.
+>
+> **Build scope:** Match scope to what changed — core-only change → `just build-quicker`; multi-module → add `--am`; full rebuild → `just build`. After a core rebuild, restart to pick up the new image: `just dev-restart 8080`. Silent failures are rare; slow builds are common.
+>
+> **Build visibility:** Both `just build` and `just build-quicker` filter Maven output to phase transitions and errors — full log is saved to `/tmp/dotcms-build.*.log` for detailed inspection. To investigate a failure without loading the full log: `grep '^\[ERROR\]' /tmp/dotcms-build.<id>` shows only error lines. If the Docker image build fails with a stale layer SHA, run `docker builder prune -f` then retry.
+>
+> **Server URLs:** `dev-start-on-port PORT` fixes the app port to what you specify (e.g. `:8080`). The management port (8090 inside container) is **always** mapped to a dynamic host port regardless. Use `just dev-urls` after any start or restart to get the actual URLs — it queries Docker live and is the only reliable source for the health endpoint port.
+>
+> **Agent log strategy:** Prefer targeted commands over loading full logs into context. Use `just dev-health` (one line) to check liveness. On build failure, read only the `[ERROR]` lines from the saved log. Load the full log only when errors alone are insufficient to diagnose the problem.
+>
+> **Frontend dev:** `nx serve` serves Angular files directly from disk at `:4200` with hot-reload — it does NOT use the WAR embedded in Docker. Edit files in `core-web/` and changes appear instantly; no backend rebuild or restart needed for frontend-only changes. Access the dev app at `:4200`, not `:8080/dotAdmin`.
+>
+> **Frontend proxy:** `just dev-start-frontend` discovers the backend app port from Docker at startup and injects it as `DOTCMS_HOST` into the nx serve proxy config (`proxy-dev.conf.mjs`). If no backend container is running it falls back to `:8080`. The proxy target is fixed at frontend startup time — if the backend is restarted on a different port, restart the frontend dev server too.


this looks like a lot of instructions... why just don't explain the loops of... code, build, run, test, stop, code, build...

fmontes · 2026-03-05T23:08:30Z

AGENTS.md

+yarn run start-dev                                          # tests against :4200 (requires backend on :8080)
+yarn run start-local                                        # tests against :8080


why two? can't we simplify?

fmontes · 2026-03-05T23:09:01Z

AGENTS.md

+
+## Gotchas
+
+- **Pre-commit hooks require SDKMAN** — use `--no-verify` on commits in environments without it


let's move the precommit to prepush so the agents can commit multiples times fast.

github-project-automation bot added this to dotCMS - Product Planning Feb 25, 2026

github-actions bot added the Area : Documentation PR changes documentation files label Feb 25, 2026

cursoragent added 7 commits February 26, 2026 17:26

docs: add AGENTS.md with Cursor Cloud specific instructions

bc428f0

docs: update AGENTS.md with Maven Docker plugin workflow and vfs driv…

1af2cb0

…er requirement

docs: clarify that Maven handles yarn install automatically

c0f567b

docs: fix AGENTS.md to reflect dynamic ports from just dev-run

efb401f

docs: use fixed port 8082 for consistent Cloud VM usage

9b34cc2

docs: replace /dist workaround with root-cause explanation of NX vite…

80e1ccc

… path bug

docs: rewrite AGENTS.md — minimal, references CLAUDE.md, Cloud VM got…

c9ed84b

…chas only

cursor bot force-pushed the cursor/development-environment-setup-e028 branch from a0515c1 to c9ed84b Compare February 26, 2026 17:27

cursoragent added 6 commits February 26, 2026 17:31

docs: symlink CLAUDE.md → AGENTS.md for true single source

489b861

docs: note Java 25 migration and parallel CI workflows

38fa89d

docs: reference justfile as command alias source and syntax reference

b1f8053

github-actions bot added the Area : Frontend PR changes Angular/TypeScript frontend code label Feb 26, 2026

github-actions bot added Area : Backend PR changes Java/Maven backend code Area : SDK PR changes SDK libraries labels Feb 26, 2026

spbolton and others added 6 commits February 26, 2026 18:08

docs: add design doc for dotcms-agent-tests skill

909fe89

Captures the architecture for validating AI agent progressive context gathering using worktrunk-isolated sub-agents and a review agent scorer. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: add implementation plan for dotcms-agent-tests skill

815a5b2

Step-by-step plan covering skill creation, 4 test cases (BE-001/002/003, FE-001), RED/GREEN baseline runs, AGENTS.md gap fixes, and PR scope. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/cursor/development-environment-s…

fafb5c3

…etup-e028' into cursor/development-environment-setup-e028

spbolton changed the title ~~Development environment setup~~ docs: AGENTS.md improvements validated by agent test suite Feb 26, 2026

spbolton added 2 commits February 26, 2026 19:06

spbolton and others added 4 commits February 27, 2026 11:43

fmontes requested review from Copilot, fmontes and nicobytes and removed request for Copilot March 2, 2026 18:23

Copilot started reviewing on behalf of fmontes March 2, 2026 18:24 View session

spbolton marked this pull request as draft March 3, 2026 18:43

fmontes requested changes Mar 5, 2026

View reviewed changes

		yarn run start-dev # tests against :4200 (requires backend on :8080)
		yarn run start-local # tests against :8080


		## Gotchas

		- Pre-commit hooks require SDKMAN — use `--no-verify` on commits in environments without it

Conversation

spbolton commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

Scope

Test plan

Uh oh!

cursor bot commented Feb 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

spbolton commented Feb 25, 2026 •

edited

Loading