Agent workflows

ldev is what gives an AI agent an execution layer on Liferay.

That sounds like a marketing line, but it is a technical statement. Most critical Liferay operations — importing structures, exporting templates, migrating articles, bootstrapping environments — only exist in the admin UI or in uneven APIs. An agent cannot click. So without a CLI like this, an agent connected to a Liferay system can mostly observe, not operate.

ldev is the same CLI a developer uses, plus the wiring (bootstrap files, installed skills) that lets an agent call the same workflows from inside an editor.

What ldev provides for agents

Layer	What it does	When
CLI with structured output	Canonical execution contract. Every workflow returns JSON.	Always
npx skills add https://github.com/mordonez/ldev	Installs workflow skills into .agents/skills/. The agent knows how to use ldev.	Always
ldev ai bootstrap --intent=...	Aggregates project context + intent-specific doctor checks for the agent's first turn.	Recommended
docs/ai/AGENTS.md (copy-paste)	Agent entrypoint committed to the project repo so all editors auto-load the skills.	For team repos

Get started

Install skills so the agent knows how to use ldev:

npx skills add https://github.com/mordonez/ldev

That is enough to start. Re-run it after each ldev update to pick up skill changes.

Set up a project repo

For team repos, copy the agent entrypoint file so all editors auto-load the skills:

# Standard ldev-native project:
cp docs/ai/AGENTS.md ./AGENTS.md

# Liferay Workspace project:
cp docs/ai/AGENTS.workspace.md ./AGENTS.md

Then create .claude/skills/ so npx skills add can place Claude Code symlinks:

mkdir -p .claude/skills

See docs/ai/ for full setup instructions. In Blade workspaces, ldev coexists with the official AI folders rather than replacing them.

Context snapshots

Use ai bootstrap so an agent has the same project facts and readiness picture a developer would use.

ldev ai bootstrap --intent=discover --json
ldev ai bootstrap --intent=develop --json
ldev ai bootstrap --intent=deploy --json
ldev ai bootstrap --intent=troubleshoot --json
ldev ai bootstrap --intent=migrate-resources --json
ldev ai bootstrap --intent=osgi-debug --json

Use --cache <seconds> to reuse the result for the same intent and working tree.

Where knowledge lives

The AI layer is easier to maintain if each kind of knowledge has one home:

• .agents/skills/* — vendor skills from npx skills add
• .agents/skills/project-* — project-owned workflow skills
• docs/ai/project-context.md — long-form project context

Structured portal context for agents

Agents consume the same inventory commands developers do — every call returns consolidated context that would otherwise need several Headless API calls:

ldev portal inventory sites --json
ldev portal inventory pages --site /global --json
ldev portal inventory page --url /home --json
ldev portal inventory structures --site /global --with-templates --json
ldev portal inventory where-used --type structure --key BASIC --site /global --json

For structure/template work, inventory structures --with-templates is the right first call.

For impact analysis, use inventory where-used after the resource key is known. It gives agents a task-shaped answer to "which Pages use this fragment, widget, Structure, Template, or ADT?" before a mutation is proposed.

Prefer the scoped form with --site whenever the Site is already known.

The agent runtime contract

Phase	When	Commands
Pre-flight	Routing, readiness, or mutations	ldev ai bootstrap --intent=discover --json or --intent=develop --json
Health check	Task touches runtime	ldev ai bootstrap --intent=deploy --json, ldev doctor --json, ldev status --json
Discovery	Task mentions a portal surface	ldev portal inventory ...
Pre-mutation check	Before any resource change	ldev resource import-* --check-only for supported imports; validate fragment source before import-fragment
Mutation	After check-only passes	ldev resource import-*, ldev deploy ...
Post-mutation verify	After any mutation	Resource changes: read back via ldev resource structure/template/adt / ldev resource export-* / ldev portal inventory ... --json. Runtime/deploy changes: ldev logs diagnose --since 5m --json, ldev portal check --json.

Key invariants (full list in AGENTS.md → Safety Invariants):

• Always read liferay.portalUrl from context — never assume.
• Always consume --json. Never parse human-readable output.
• Always run --check-only before resource mutations that support it.
• Never use plural resource commands without explicit human approval.
• Do not treat ldev logs diagnose as universal verification for resource imports; prefer read-after-write evidence from ldev resource / ldev portal inventory.
• Diagnose before retrying a failed command.

Keep skills up to date

After pulling a new version of ldev, refresh skills:

npx skills add https://github.com/mordonez/ldev

To update agent meta-files (AGENTS.md, etc.), re-copy them from docs/ai/.

Why this matters

Without this layer, an agent connected to Liferay can read state but cannot operate it. With it, an agent can stand up an environment, import a structure, run a migration check, deploy a module and verify the result — end to end, with the same evidence a developer would gather.

That is what makes ldev useful for AI workflows. Not the buzzword. The fact that the operations actually exist as commands.

Put differently: we did not build AI features. We fixed the systems problem in Liferay — operations as data, reproducible environments, isolated runtimes, guardrails before mutation, structured output. All of that was already worth doing for humans. The AI integration came along for the ride. See Why ldev Exists for the long form.