Content Driven Development

Content Driven Development (CDD)

Orchestrate the Content Driven Development workflow for AEM Edge Delivery Services. This workflow ensures code is built against real content with author-friendly content models.

CRITICAL: Never start writing or modifying code without first identifying or creating the content you will use to test your changes.

When to Use This Skill

Use CDD for ALL AEM development tasks:

• ✅ Creating new blocks
• ✅ Modifying existing blocks (structural or functional changes)
• ✅ Changes to core decoration functionality
• ✅ Bug fixes that require validation
• ✅ Any code that affects how authors create or structure content

Do NOT use for:

• Documentation-only changes
• Configuration changes that don't affect authoring
• Research tasks that don't require making any code changes yet

Philosophy

Content Driven Development prioritizes creating or identifying test content before writing code. This ensures:

• Code is built against real content
• Author-friendly content models
• Validation throughout development

Optional: Understanding CDD Principles

Read references/cdd-philosophy.md if:

• User asks "why" questions about content-first approach
• You need to understand reasoning behind CDD decisions
• You're unsure whether to prioritize author vs developer experience

Otherwise: Follow the workflow steps below

Step 0: Create TodoList

FIRST STEP: Use the TodoWrite tool to create a todo list with the following 8 tasks:

1. Start dev server (if not running)

   • Success: Dev server running, can access http://localhost:3000

2. Analyze & plan

   • Success: Clear understanding documented + acceptance criteria defined

3. Design content model

   • Success: Content structure documented and validated

4. Identify/create test content

   • Success: Test content accessible covering all scenarios

5. Implement

   • Success: Functionality works across all viewports

6. Lint & test

   • Success: All checks pass

7. Final validation

   • Success: All acceptance criteria met, everything works

8. Ship it

   • Success: PR created with preview link for validation

Mark todo complete when: Todo list created with all 8 tasks

Step 1: Start Dev Server

Check if dev server is running:

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

Expected: 200 (server running) or connection error (server not running)

If not running, start it:

aem up --no-open --forward-browser-logs

Notes:

• Run in background if possible (dev server needs to stay running)
• Requires AEM CLI installed globally: npm install -g @adobe/aem-cli
• Alternative: npx -y @adobe/aem-cli up --no-open --forward-browser-logs

IMPORTANT: Check the command output for errors. Common issues:

• Port 3000 already in use
• AEM CLI not installed
• Configuration errors

After starting, verify it's running:

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

Expected: 200

Success criteria:

• ✅ Dev server running
• ✅ http://localhost:3000 returns 200
• ✅ No errors in server startup output

Mark todo complete when: Dev server confirmed running and accessible

Step 2: Analyze & Plan

Invoke: analyze-and-plan skill

Provide:

• Task description from user
• Screenshots, design files, or existing URLs to match design from (if available)

The analyze-and-plan skill will:

• Guide you through task-specific analysis
• Help define acceptance criteria
• Optionally analyze visual designs/mockups if provided
• Create documented analysis for reference

Success criteria:

• ✅ Requirements analyzed
• ✅ Acceptance criteria defined
• ✅ Analysis documented to file for later steps

Mark todo complete when: Analysis documented and acceptance criteria defined

Step 3: Design Content Model

Skip if: CSS-only changes that don't affect content structure

Invoke: content-modeling skill

Provide:

• Analysis from Step 2 (content requirements, author inputs)
• Block name and purpose

The content-modeling skill will:

• Design table structure (rows, columns, semantic formatting)
• Validate against best practices (4 cells/row, semantic formatting)
• Document content model for authors

Success criteria:

• ✅ Content model designed (table structure defined)
• ✅ Validated against best practices
• ✅ Content model documented

Mark todo complete when: Content model designed and documented

Step 4: Identify/Create Test Content

Goal: End this step with accessible test content URL(s) covering all test scenarios

Choose the best path based on your situation:

Option A: User Provided Test URL(s)

When to use: User already has content and provided URL(s)

What to do:

1. Validate URL loads: curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path
2. Expected: 200 status
3. Document URL(s)
4. Mark complete

Option B: New Block (No Existing Content)

When to use: Building a brand new block that doesn't exist yet

What to do:

1. Skip search (nothing exists yet to find)
2. Create test content using one of these approaches:

Approach 1: CMS Content (Recommended)

1. Ask user to create content in their CMS (Google Drive/SharePoint/DA/Universal Editor)
2. Provide content model from Step 3 as reference
3. Wait for user to provide URL(s)
4. Validate: curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path
5. Expected: 200 status

Using DA: If you need to push HTML content programmatically to DA (rather than asking the user to author it), invoke the da-auth skill first to obtain a valid DA_TOKEN, then use the DA Admin API (POST https://admin.da.live/source/{org}/{repo}/{path}) to push the content and trigger a preview.

Approach 2: Local HTML (Temporary)

1. Create HTML file in drafts/tmp/{block-name}.plain.html
2. Follow structure from Step 3 content model
3. Read references/html-structure.md for local HTML file format guidance
4. Restart dev server: aem up --html-folder drafts --no-open --forward-browser-logs
5. Validate: curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/drafts/tmp/{block-name}
6. Expected: 200 status
7. Note: User must create CMS content before PR (required for preview link)

Option C: Existing Block

When to use: Modifying, fixing, or styling an existing block

What to do:

First: Search for existing content

1. Invoke find-test-content skill
2. Provide: block name, dev server URL (optional, defaults to localhost:3000)

What find-test-content will do:

• Search for existing content pages containing the block
• Automatically detect and report all variants found
• Report: URLs with instance counts and variant info

Then: Assess search results

If sufficient content found:

1. Document URL(s)
2. Validate URLs load: curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path
3. Expected: 200 status
4. Mark complete

If no content found OR insufficient coverage:

1. Create additional test content using approaches from Option B
2. Validate URLs load
3. Mark complete

Success criteria:

• ✅ Test content accessible at known URL(s)
• ✅ Content covers all test scenarios (variants, edge cases)
• ✅ URLs validated (return 200)

Mark todo complete when: Test content identified/created and validated

Step 5: Implement

Invoke: building-blocks skill

Provide:

• Content model from Step 3 (if applicable)
• Test content URL(s) from Step 4
• Analysis/requirements from Step 2
• Type of changes: new block, existing block modification, CSS-only, etc.

The building-blocks skill will:

• Guide implementation approach based on change type
• Handle JavaScript decoration (if needed)
• Handle CSS styling (mobile-first, responsive)
• Ensure iterative testing in browser throughout development

Success criteria:

• ✅ Code implementation complete
• ✅ Functionality works across all viewports (mobile, tablet, desktop)
• ✅ No console errors

Mark todo complete when: building-blocks skill reports implementation complete and working across viewports