Work in progress
Content SDK · Agentic flow · Work in progress

An agentic flow for SitecoreAI head apps.

I'm in the middle of building a proper agentic-supported workflow for Sitecore Content SDK head applications — two tracks, eleven custom skills, and a stack of findings that already paid for themselves. This page is the in-flight diary.

Back to SitecoreContact Me
Status
In the middle of building. The flow exists, eleven custom skills are live, the build-side agents auto-load Sitecore knowledge when platform_target == content-sdk. What you see below is the diary, not the brochure — the wins, the open questions, and what is deliberately deferred.
What's built so far

Eleven custom skills, live.

Each one was distilled from a real session — a trap I hit, a pattern I want to keep, or a decision the agents will need to make again. They auto-surface by description match; agents do not need to be told which to load.

sitecore-cli-cloud-workflow

Device-flow login → project list → environment list (project-id required) → connect → user.json patch → ser pull. Every CLI trap captured.

content-sdk-debug-layout-probe

/api/layout-debug route + ResolverProbe component + InstrumentedFrame wrapper. The triple-toolkit for any "what is Sitecore actually delivering" question.

content-sdk-playground-pattern

playgrounds/<topic>/ workspace layout at repo root for learning a feature without polluting a real product. Used for everything in this page.

content-sdk-component-naming-traps

Five gen-map traps. The big one: only the Sitecore-registered .tsx (and variants) live under src/components/<X>/; types, queries, sub-components must live elsewhere or they auto-register.

content-sdk-theme-hydration-pattern

Dark+light+system theme stack — public/theme-init.js preflight, useSyncExternalStore provider, mounted-flag for SSR-safe styling, Tailwind v4 @theme tokens.

content-sdk-resolver-patterns

Catalog of Sitecore data-delivery patterns. Key insight: 4 SXA content-resolver variants (Datasource/Context × Item/Children) collapse to only 2 React-side shapes.

content-sdk-variants-vs-siblings

Decision skill — variant (same rendering, different FieldNames) vs sibling (separate rendering). SDK-verified FieldNames resolution flow + Headless Variant authoring requirement.

sitecore-edge-graphql-capture

curl recipe for capturing Edge GraphQL snapshots. Three hard limits documented: 15-depth introspection, complexity-by-pagination, no /schema endpoint.

content-sdk-component-level-navigation

Production navigation pattern — component-level GraphQL fetch (server L1 + lazy L2 per-hover) instead of fighting the SXA Navigation Content Resolver. Scales to any depth.

nextjs-route-handler-vs-server-action

General Next.js rule: reads → Route Handler, mutations → Server Action. Server Actions auto-trigger router.refresh() which wipes client state on reads — looked like endless loading flicker.

content-sdk-website-build-flow

The umbrella. Canonical phase sequence (0–7), NEW-vs-EXISTING fork, baseline-copy + token-replacement mechanics, upfront operator question batch, per-component cycle template.

The flow

Eight phases, two tracks.

A CMS track (operator works in Sitecore) and a Head-app track (AI works in code) running in parallel, syncing at every stop gate. The flow is the same for new and existing sites — the only difference is Phase 02, where existing sites probe + pull and new sites build static-first with a content-model spec for the operator.

00Discovery

Intent + the critical fork

One paragraph "what we are building" + the NEW-site vs EXISTING-site question that drives the path. NEW = static-first build, no probe target. EXISTING = probe + pull, real shapes from day one.

operator answers in /create-prd
01Baseline + scaffold

Copy CMS-side, scaffold head-app side

Copy the SitecoreAI_Authoring baseline (CMS-side scaffolding: sitecore.json, xmcloud.build.json, authoring/, .sitecore/, empty sites/). Replace <SITE_NAME> + <SITE_COLLECTION_NAME> tokens. Run the canonical create-content-sdk-app inside sites/<SITE_NAME>/.

npx create-content-sdk-app@latest nextjs
02Connect

Probe + pull (existing) — or acknowledge gap (new)

EXISTING: dotnet sitecore cloud login → ser pull → edge snapshot per the capture skill. NEW: tell the operator there is no Sitecore content yet; the static-first build will produce a content-model spec they create in Sitecore later. Developer MCP will eventually automate this.

ser pull -n <env> + edge-snapshot/
03Chrome

Theme + site shell

Build the design tokens, theme provider with FOUC preflight, header, footer, theme toggle. Dark+light+system is non-negotiable. Infrastructure lives in src/ui/, src/site/ — never src/components/ (would auto-register as Sitecore renderings).

tailwind v4 @theme + globals.css
04Navigation

Component-level data fetching

Build navigation with server L1 fetch + lazy L2 per-hover via a Route Handler. Not a Server Action (auto-refresh wipes state). Not the SXA Navigation Content Resolver (opaque). Pattern scales to any depth via recursion.

/api/nav-children + NavBranch recursive
05Components

Per-rendering build loop

For each Sitecore rendering: probe via /api/layout-debug → identify pattern (one of 5) → decide variant vs sibling → scaffold (helpers OUT of src/components/<X>/) → implement with SDK field components → register via gen-map → verify → operator visual approval. Each cycle is its own tranche.

looped until inventory is empty
06Verify

Smoke + walkthrough

npm run build green. Lint + typecheck clean. Per-page /api/layout-debug capture matches expected shape. manifest.smoke_outcomes one entry per published page, all "pending" until operator confirms no MissingComponent placeholders + nav works + content renders.

smoke gates per page
07Ship

Strip debug, deploy, smoke prod

Remove /api/layout-debug + /nav-debug. Verify .env.example is current. Operator triggers hosting deploy + publishes any final CMS content. Final smoke on the production URL.

/ship
Live findings

The wins that paid for themselves.

Each of these turned a half-day debug session into a one-line rule the agents now follow. Every entry below is encoded as one of the eleven skills above — they are not aspirations, they are the operating playbook.

🧮

4 resolver variants → 2 React shapes

Datasource + Context, each in Item + Children form, look like four distinct patterns. They collapse to TWO React-side payload shapes (single-item flat hash; children-list wrapper). Same React code handles both members of each pair.

🚦

Edge has hard, undocumented limits

15-level depth limit kills the standard IntrospectionQuery. Query complexity scales with pagination + nesting — first:100 with nested fields gets rejected, first:10 works. There is no /schema endpoint; POST + per-type introspection is the only path.

🌀

Server Action for reads = endless flicker

Server Actions auto-trigger router.refresh() after returning. For mutations, that is the feature. For client-triggered reads from a hover handler, it wipes every NavBranch state, the dropdown closes, the user re-hovers, repeat. Route Handlers have zero refresh side-effect; that is the right tool for reads.

🧭

Component-level nav > SXA Navigation Resolver

The resolver was returning fields: [] with no clear cause. Replacing it with a custom GraphQL query — server L1 with hasChildren flag, lazy L2 per-hover — is more predictable, type-safe, recursive to any depth, and stays under Edge limits because each branch fetch is independent.

🪤

Support files inside component folders auto-register

Place types.ts, queries.ts, a NavBranch.tsx client child, or an actions.ts under src/components/<X>/ — gen-map registers them as variants of <X> or as standalone Sitecore renderings. Only the rendering .tsx (plus .<Variant>.tsx siblings) belongs in that folder. Everything else lives in src/lib/, src/ui/, or src/app/api/.

🔤

Generic parameter names collide silently

Naming a rendering parameter "Levels" made it disappear from the Pages editor — collision with a base-template field. Renaming to "Level" (singular) made it visible. The rule: namespace your rendering-parameter names or use singular forms; avoid Levels / Depth / Style / Items.

Honest closer
The flow plugs into my existing agentic pipeline — no new commands, no new agents, no parallel checklist. The five build-side agents (Architect, UI Designer, Lead Developer, QA, Developer) load Sitecore-specific knowledge when manifest.platform_target == content-sdk. The skills hold the domain knowledge; the agents stay framework-neutral. That is the whole architecture.
What's open

The honest backlog.

Some of this is parked because we have a workaround; some is deliberately deferred until a real project asks for it. None of it is hidden — if you are evaluating this for a project, these are the gaps you would inherit.

Pages Editor preview-mode behaviour

In editor mode, every rendering is wrapped in editing chrome (overlay buttons, drag handles). Some interactions behave differently from the live page. Still mapping which findings only apply to live and which apply to editor too.

Navigation Content Resolver — partially verified

The SXA Navigation Content Resolver returns the right shape only sometimes; we built around it with a custom query. The exact param combinations that make it work are still unconfirmed. Parked while the component-level pattern carries the workload.

i18n / multilingual

Deferred. The playground has four languages on file (en, de-DE, ja-JP, zh-CN) but the navigation query hardcodes language="en". Wiring next-intl + per-language Edge fetches + dictionary loading is the next infrastructure topic.

Personalization

Deferred. @sitecore-content-sdk/personalize integration, A/B variants, audience targeting. Distinctively Sitecore; needs its own probing session.

Forms

Deferred. Sitecore Forms rendering, validation, submission flow. Common requirement for any real site; slot for its own skill once the first project needs it.

Custom proxy chain

Deferred. Adding stages beyond Locale → Multisite → Redirects → Personalize. Only matters for non-standard routing or cross-site behaviour.

Watching this take shape?

Want a Content SDK head app built this way?

The flow is being battle-tested. If you have a head-app project on the horizon and want to be the next dogfood case, reach out.

Mail MeAgentic Pipeline