Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/build-site

build-site

Verified

Orchestrate a complete Liferay site experience from a single prompt. Composes objects, business logic, fragments, pages, roles, and theme into a working site. Use when the user asks to "build a site", "create a site experience", or describes a multiobject, multipage scenario. Calls all other skills in sequence.

Build Site

One command orchestrator. The user describes the site; this skill calls the right subskills in the right order.

When to Invoke

  • "Build a Bookstore site with an Author object, a Book object, and a home page"
  • "Create a site experience for customer onboarding"
  • "Scaffold the full job board site"
  • Any multiobject, multipage request that spans data and presentation

Standing Requirements

These hold on every site build whether or not the user asks for them. Do not wait to be told.

  1. Everything ships in the workspace, reproducible from a clean environment. Do not satisfy a request for data, pages, fragments, or styling by mutating only the running instance — write it into the tree first, then apply it. A site that cannot be rebuilt from what is checked into the workspace is not finished, however correct it looks in the browser.

    Keep it to as few projects as the classification rules permit, but a whole site cannot be one project. siteInitializer is batch; themeCSS is frontend; handlers are microservice; those three can never share a client-extension.yaml. The initializer project carries the siteInitializer plus exactly one oAuthApplicationHeadlessServer and nothing else — a theme or an objectAction added to it fails at createClientExtensionConfig, after the assemble tasks have already printed success. See rules/client-extension-types.md → "Which Types May Share a Project".

    So the reproducible unit is the workspace, not a single directory. Express the site's look through what the initializer tree can carry — style book, master page, fragment CSS, layout-set settings, and a themeCSS CET bound in the master's page-definition.json settings.themeCSSClientExtension (ERC "LXC:" + <config-erc>), which cascades to every page and survives reprovision (rules/site-initializer-format.md → "Binding Design to the Master via settings"). The theme is still a sibling project (type classification rule), but its application is tree expressible — no manual Design → Theme step.

  2. Objects are the data layer. Model entities as Liferay Object definitions. Do not reach for web content structures or a Service Builder module for structured application data, even when the modules directory exists in the workspace.

  3. Verify by rendering, not by status code. A page returning 200 with an empty content area is the pack's most common silent failure. Fetch each page and confirm its fragments produced markup before reporting success.

  4. Verify as the audience. When a flow is meant for unauthenticated visitors, exercise it without a session cookie. An admin authenticated check hides missing Guest permissions.

  5. Report what does not work. Name every placeholder, skipped step, and unverified claim. An overstated success is worse than a reported failure.

Workflow

The sequence below is the canonical order. Skip phases the user has not requested; do not add phases they have not asked for.

Phase 0: Scope Confirmation

Before calling any subskill, confirm the scope with the user:

  1. Site name — what to call the site

  2. Objects — list of entity names with their key fields and relationships

  3. Pages — list of pages and their purpose

  4. Roles — named roles and their intended access (viewer, editor, admin)

  5. Theme — any color, font, or visual requirement (optional)

  6. Audience — who the site is actually for: anonymous visitors, or a signed in user. This decides every verification step later, and getting it wrong wastes a full cycle in either direction. An admin only demo needs no Guest grants and must be checked signed in; a public site needs resource-permissions.json and must be checked signed out. Ask; do not infer it from the fact that a page is public.

Proceed only after the user confirms or corrects the scope list.

Settle the Reprovision Surface Before Provisioning Once

This is the single largest time sink in a site build. A whole class of change costs another run of the initializer each time it is discovered. "Reprovision" below means firing the initializer again with a clean redeploy — that run upserts pages, composition, and fragments onto the existing site (see rules/site-initializer-format.md → "Firing the initializer again UPSERTS"); delete + redeploy is only needed to remove things or recover from a doubtful upsert. Each cycle still costs a full wait to build, deploy, and import, and the number of cycles is decided here, before Phase 4, not later.

ChangeCost after the first provision
Object definition, field, relationship, entry dataLive — object-admin API, no reprovision
Theme CSS content (CET already bound to the master)Live — blade gw deploy
Binding a themeCSS CET or style book onto the masterReprovision
Fragment HTML / CSS / JS, or a new fragmentReprovision
New page, or recomposing an existing oneReprovision
Adding or changing a master pageReprovision, and it rewrites every page definition
Style book, navigation menu, layout set settingsReprovision

So before writing the first fragment, answer these — each wrong guess is one cycle:

  • Is there a master page? Retrofitting one later touches every page-definition.json (each needs settings.masterPage.key and version: 1.1). If the site has a branded header or footer — and almost every real site does — build it in Phase 5, not after the theme prompt.
  • What is the complete page list, including the ones that are not navigation items: thank you, confirmation, error, "no results" pages. A form almost always implies a landing page.
  • Which fragments carry JavaScript, and have they been reasoned through once for timezone, permissions, and number parsing? See the trap table below.
  • Does the theme need a themeCSS CET? Decide now: it is a sibling project whose binding lives in the master's page-definition.json settings block, so adding or changing it later is a master composition change — one more reprovision (skills/theme-and-design/SKILL.md).

Batch everything that costs a reprovision into as few passes as possible. A planned build provisions once or twice; a reactive one provisions five times.

Trap Preflight

Five silent failures account for most of the rework in this pack. Each one builds, deploys, and renders — the defect only shows on close reading. Check them while authoring, not after.

TrapRuleWhere
fragment.json "type"Always "component". "section" breaks the whole headless-admin-fragment listing with 400 Invalid enum valuescaffold-fragment
Literal text overrideReplaces the editable's inner <h1>/<h2>, so tag only CSS selectors miss itmanage-pages
DateTime in fragment JSUse the UTC getters, or times shift into the visitor's timezonemanage-pages
Heading font across the siteContent fragments must not declare font-weight on headings the master rule ownstheme-and-design
Reserved object field namesstatus is taken — use <entity>Status. Inside an initializer this rolls back the entire sitemanage-objects

The canonical model is site initializer first: the siteInitializer CET tree is the single source of truth, and the site is created by triggering the initializer rather than by calling the live page API. After the initial build, iterate by editing the source tree and applying each change by the cheapest reliable path — see "Iterating on the Site" below and the spine in rules/site-initializer-format.md.

Phase 1: Prerequisites

Call feature-flags for the full set of flags the workflow needs:

ScenarioRequired Flags
Fragment composition via APILPD-39244
Object entry shares (collaborators)LPD-17564 on 2026.Q1 and 2026.Q2; none on 2026.Q3
MCP transportLPD-63311, plus the MCPServerConfiguration switch on 2026.Q3 (see skills/mcp-server/SKILL.md)

Report the gap table. Enable flags only after explicit user confirmation. Bounce Tomcat if any flags are written, following liferay-rules.md → "Server Restarts".

Phase 2: Transport Selection

Run the probe in skills/mcp-server/SKILL.md → "Audit the Current State First". It posts an initialize request with credentials; a bare HEAD does not, and on 2026.Q3 every unauthenticated request gets 401.

  • 200: MCP is available. Use it for all subsequent API calls: the call-http-endpoint tool on 2026.Q1 and 2026.Q2, the tool set meta tools on 2026.Q3 (see skills/mcp-server/SKILL.md → "Tool Sets Replace call-http-endpoint").
  • 404 on 2026.Q3: The MCPServerConfiguration switch is probably off. Enable it per skills/mcp-server/SKILL.md before falling back.
  • Otherwise: Fall back to direct curl calls with Basic auth.

Phase 3: Data Model

For each object in the confirmed scope, call manage-objects:

  1. Create and publish the object definition.

  2. Add all fields.

  3. Add picklists (if any field references a picklist).

  4. Add relationships between objects (parent → child).

  5. Add validations.

  6. For a count of child entries or the capacity they leave, such as places left, add an Aggregation field (manage-objects → "Aggregation Fields"). Filter it when only some children count.

For each business logic requirement, call manage-object-logic:

  1. Choose the trigger and action type.

  2. Create notification templates if needed.

  3. Create the object action.

  4. When a reviewer approves or rejects each entry, follow "Approval Workflow" rather than linking the stock Single Approver, which cannot set a rejected status.

Phase 4: Site Initializer Scaffold

Call scaffold-client-extension with type siteInitializer to create the CET that will provision the site. This tree is the source of truth for the site's fragments, pages, theme metadata, and roles. Populate it in Phases 5–8 per rules/site-initializer-format.md, then trigger it in Phase 9.

Phase 5: Fragments

For each unique layout section needed by the page list, call scaffold-fragment:

  1. Create the fragment source files inside the initializer tree at site-initializer/fragments/group/<collection-key>/fragments/<fragment-name> (note the required fragments nesting level under the collection). For the initial build, the content may be hardcoded (static text and images); later iterations bind it to objects.

  2. Record each fragment's key (its <fragment-name> directory name) for Phase 6 — page definitions reference it as fragment.key with siteKey: "[$GROUP_KEY$]".

Phase 6: Pages

For each page in the confirmed scope, call manage-pages to author it in the initializer:

  1. Write site-initializer/layouts/<NN-page-name>/page.json with the correct type (Content Page default).

  2. Write page-definition.json composing the page with fragment elements (using keys from Phase 5).

  3. Add the navigation menu and SEO metadata via the initializer's layout-set directory and page metadata.

The pages come into being when the initializer is triggered in Phase 9.

Phase 7: Theme and Design (Optional)

When the user provided visual requirements, call theme-and-design:

  1. Generate and deploy the themeCSS CET.

  2. Create and assign the style book.

  3. Create the master page with header and footer fragments.

Phase 8: Roles and Permissions

For each role in the confirmed scope, call manage-roles-permissions:

  1. Create the role.

  2. Assign permissions on each object definition.

  3. Assign permissions on each page (restrict visibility if needed).

Phase 9: Provision the Site

Deploy the CET and trigger the initializer. This creates the site with its fragments, pages, and roles in one pass:

# Deploy the site initializer CET

cd client-extensions/<site-init-name> && blade gw deploy

# Trigger it to create the site

curl \
	--data '{
		"membershipType": "open",
		"name": "<Site Name>",
		"templateType": "site-initializer",
		"templateKey": "<workspace-id>-site-init"
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites" \
	--user "test@liferay.com:test"

Caution: resolving a site initializer template through POST /sites is unreliable (the current Site DTO uses templateKey, not templateExternalReferenceCode). The portable path is to let the siteInitializer CET autoprovision on deploy, and to reprovision by delete then redeploy — see rules/site-initializer-format.md.

Save the site's externalReferenceCode as <site-erc> from the response.

Phase 10: Verification

Confirm the site is functional:

# Site exists

curl \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites/<site-erc>" \
	--user "test@liferay.com:test" \
	| jq '{externalReferenceCode, name}'

# Pages exist

curl \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites/<site-erc>/site-pages" \
	--user "test@liferay.com:test" \
	| jq '[.items[] | {name, friendlyUrlPath, type}]'

# Object definitions published

curl \
	--silent \
	--url "http://localhost:${PORT}/o/object-admin/v1.0/object-definitions?filter=status%20eq%20%27approved%27" \
	--user "test@liferay.com:test" \
	| jq '[.items[] | {name, status}]'

# Probe site home page — a 200 alone does not mean it rendered

curl \
	--silent \
	--url "http://localhost:${PORT}/web/<site-friendly-url>" \
	| grep --count "<fragment-marker-or-known-content>"

Per Standing Requirement 3, fetch each page's body and confirm the expected fragment content is present. An empty content area returns 200.

Where the site serves unauthenticated visitors, repeat the critical path with no credentials and no cookie jar — see Standing Requirement 4.

Report the final state: objects created, pages created, roles created, site URL, and anything left placeholder or unverified.

Iterating on the Site

After the initial build, the user improves the site through natural language prompts. The initializer tree stays the source of truth: edit the source files first, then apply the change by the cheapest reliable path. The initializer runs only at site creation, so only page changes force a reprovision.

Prompt IntentSource EditHow to ApplyReprovision?
"Give me a unified theme"themeCSS CET (+ style book, master page)theme-and-design → blade gw deployNo
"Replace the hardcoded list with an object"object definition + data in the batch directorymanage-objects → object-admin API / batch importNo
"Edit / restyle a fragment"fragments/group/<key>/...scaffold-fragment → reprovision (there is no portable live fragment import endpoint)Yes
"Add a new fragment"new fragments/group/<key>/...scaffold-fragment → reprovisionYes
"Add a page" / recompose a pagelayouts/<NN>/page*.jsonreprovision (delete + recreate from initializer)Yes

Object definitions and entries are scoped at the company level, so a reprovision for a page change preserves runtime data. See rules/site-initializer-format.md for the reprovision commands.

Example Prompt Interpretation

User: "Build a Bookstore site with an Author object (name, bio), a Book object (title, isbn, linked to Author), a home page listing Books, and a Reader role that can only view Books."

Scope confirmation:

  • Objects: Author (name: Text, bio: LongText), Book (title: Text, isbn: Text, authorId: Relationship to Author)
  • Pages: Home (Content Page, lists Books via a fragment)
  • Roles: Reader (VIEW on Book object, VIEW on Home page)

Execution order: Phase 1 (flags) → Phase 2 (MCP probe) → Phase 3 (Author, Book, relationship) → Phase 4 (scaffold initializer) → Phase 5 (book list fragment in tree) → Phase 6 (home page in layouts) → Phase 8 (Reader role + page permissions) → Phase 9 (deploy + trigger initializer) → Phase 10 (verify)

Handling Partial Failures

When a phase fails:

  1. Surface the error and the raw API response to the user.

  2. Diagnose the cause (missing flag, validation error, unreachable endpoint).

  3. Ask the user whether to retry the failed phase, skip it, or abort.

  4. Do not proceed to dependent phases when a prerequisite phase has failed.

Success Signal

TODO / inferred — verify against a running bundle. Phase 10 above holds the observable checks (site, pages, published objects, home page probe); confirm on a live bundle.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall