content-driven-development

What this skill does

# 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](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:**

```bash
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:**

```bash
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:**

```bash
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](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

**Suc