updates and refinements to agents and claude context files

.agents/discover-skills

@@ -1,50 +1,86 @@
-#!/bin/bash
-# Discover available skills in .claude/skills/
+#!/usr/bin/env bash
+set -Eo pipefail
+IFS=$'\n\t'
+
+# Discover available skills in both project and global directories
 # Usage: .agents/discover-skills
 
-SKILLS_DIR=".claude/skills"
+PROJECT_SKILLS_DIR=".claude/skills"
+GLOBAL_SKILLS_DIR="$HOME/.claude/skills"
 
-if [ ! -d "$SKILLS_DIR" ]; then
-    echo "No skills directory found at $SKILLS_DIR"
-    exit 0
-fi
+process_skills_directory() {
+  local skills_dir="$1"
+  local location_label="$2"
 
-# Find all SKILL.md files
-SKILL_FILES=$(find "$SKILLS_DIR" -name "SKILL.md" -type f | sort)
+  if [[ ! -d "$skills_dir" ]]; then
+    return 0
+  fi
 
-if [ -z "$SKILL_FILES" ]; then
-    echo "No skills found in $SKILLS_DIR"
-    exit 0
-fi
+  local count=0
+  # Count skills first
+  while IFS= read -r -d '' skill_file; do
+    count=$((count + 1))
+  done < <(find "$skills_dir" -type f -name 'SKILL.md' -print0)
 
-echo "Available Skills:"
-echo "=================="
-echo ""
+  if [[ $count -eq 0 ]]; then
+    return 0
+  fi
+
+  echo "$location_label ($count skill(s)):"
+  # Generate underline matching label length
+  local len=${#location_label}
+  if [[ $len -gt 0 ]]; then
+    local underline=""
+    for ((i=0; i<len; i++)); do
+      underline+="="
+    done
+    echo "$underline"
+  fi
+  echo ""
 
-# Process each skill
-while IFS= read -r skill_file; do
-    # Extract skill name from path
+  # Iterate SKILL.md files robustly (handles spaces)
+  while IFS= read -r -d '' skill_file; do
     skill_dir=$(dirname "$skill_file")
     skill_name=$(basename "$skill_dir")
 
-    # Extract frontmatter if it exists
+    # Check for YAML frontmatter
     if head -n 1 "$skill_file" | grep -q "^---$"; then
-        # Parse YAML frontmatter
-        name=$(sed -n '/^---$/,/^---$/p' "$skill_file" | grep "^name:" | sed 's/^name: *//')
-        description=$(sed -n '/^---$/,/^---$/p' "$skill_file" | grep "^description:" | sed 's/^description: *//')
+      # Extract lines between first pair of --- delimiters
+      frontmatter=$(awk 'BEGIN{inside=0; c=0} /^---$/ {inside=!inside; if(++c==3) exit} inside==1 {print}' "$skill_file")
+      name=$(printf '%s\n' "$frontmatter" | awk -F': *' '/^name:/ {sub(/^name: */,"",$0); print substr($0, index($0,$2))}' 2>/dev/null)
+      description=$(printf '%s\n' "$frontmatter" | awk -F': *' '/^description:/ {sub(/^description: */,"",$0); print substr($0, index($0,$2))}' 2>/dev/null)
 
-        echo "Skill: ${name:-$skill_name}"
-        echo "Path: $skill_file"
+      echo "Skill: ${name:-$skill_name}"
+      echo "Path: $skill_file"
+      if [[ -n "$description" ]]; then
         echo "Description: $description"
+      fi
     else
-        # No frontmatter, show skill name and first few lines
-        echo "Skill: $skill_name"
-        echo "Path: $skill_file"
-        echo "Description:"
-        head -n 5 "$skill_file"
+      echo "Skill: $skill_name"
+      echo "Path: $skill_file"
+      echo "Description:"
+      head -n 5 "$skill_file"
     fi
 
     echo ""
     echo "---"
     echo ""
-done <<< "$SKILL_FILES"
+  done < <(find "$skills_dir" -type f -name 'SKILL.md' -print0)
+}
+
+echo "Available Skills:"
+echo "=================="
+echo ""
+
+# Check project skills
+process_skills_directory "$PROJECT_SKILLS_DIR" "Project Skills (.claude/skills)"
+
+# Check global skills
+process_skills_directory "$GLOBAL_SKILLS_DIR" "Personal Skills (~/.claude/skills)"
+
+# If no skills found at all
+if [[ ! -d "$PROJECT_SKILLS_DIR" && ! -d "$GLOBAL_SKILLS_DIR" ]]; then
+  echo "No skills directories found."
+  echo "- Project skills: $PROJECT_SKILLS_DIR"
+  echo "- Personal skills: $GLOBAL_SKILLS_DIR"
+fi

.claude/skills/analyze-and-plan/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: analyze-and-plan
+description: Analyze development requirements and define acceptance criteria for AEM Edge Delivery Services tasks. Handles new blocks, variants, modifications, bug fixes, and styling changes with task-specific guidance.
+---
+
+# Analyze & Plan
+
+Analyze what you're building and define clear acceptance criteria before writing code. This skill provides task-specific analysis guidance for different types of AEM development work.
+
+## When to Use This Skill
+
+**Invoked by:** content-driven-development skill (Step 2)
+
+Use this skill to:
+- Analyze visual designs/mockups (if provided)
+- Understand requirements for the task
+- Define what success looks like
+- Document analysis for reference throughout development
+
+## Workflow
+
+Follow these steps in order:
+
+### Step 1: Visual Analysis (if provided)
+
+**Skip if:** No screenshots, design files, or reference URLs provided
+
+**If visual materials provided:**
+
+See `resources/visual-analysis.md` for complete visual analysis guidance covering:
+
+- **Visual elements** - Layout, typography, colors, spacing, borders, shadows, effects, icons, imagery
+- **Interactive elements** - Components, states (hover/focus/active), animations, transitions
+- **Dynamic UI patterns** - Modals, tooltips, dropdowns, accordions, carousels
+- **Content structure** - Hierarchy, repeating patterns, content types
+- **Responsive behavior** - Mobile, tablet, desktop variations
+- **Systematic mapping** - Page vs component, existing patterns, block model classification
+
+**What to do:**
+1. Gather all visual materials (screenshots, designs, URLs)
+2. Use visual-analysis.md guide to systematically analyze
+3. Document findings using the provided template
+4. Extract key requirements for next steps
+
+**Output:** Visual requirements documented for use in next steps
+
+---
+
+### Step 2: Understand Requirements
+
+**What to do:**
+- Think about what you are building/fixing/modifying?
+- Consider why this is needed?
+- What's the context surrounding these changes?
+- Consider all viewports (mobile, tablet, desktop)
+- Think about the author experience and how that impacts what we do
+
+**Ask the user questions if needed:**
+- Clarify unclear requirements
+- Understand edge cases
+- Confirm assumptions
+- Get missing information
+
+**Use task-specific guidance:**
+- See "Task-Specific Analysis Guidance" section below
+- Apply appropriate guidance based on task type
+
+**Output:** A clear understanding of all requirements
+
+---
+
+### Step 3: Define Acceptance Criteria
+
+**What to define:**
+- What does "done" look like?
+- How will you validate success?
+- What should NOT break (regressions)?
+
+**Include:**
+- Visual match (if designs provided)
+- Functional requirements
+- Responsive behavior
+- Author experience
+- Performance considerations
+
+**Use task-specific guidance:**
+- See acceptance criteria guidelines in "Task-Specific Analysis Guidance" below
+
+**Output:** Specific, testable acceptance criteria
+
+---
+
+### Step 4: Document Analysis
+
+**Create markdown file at:** `drafts/tmp/{block-name}-analysis.md`
+- Use the block name being worked on (e.g., `drafts/tmp/hero-analysis.md`)
+- For non-block work, use descriptive name (e.g., `drafts/tmp/navigation-fix-analysis.md`)
+
+**File should include:**
+- Task description and context
+- Visual analysis (if applicable)
+- Requirements identified
+- Acceptance criteria defined
+- Any open questions or assumptions
+
+**Notes:**
+- This is a working artifact, not committed to git
+- Used for reference throughout development (especially in Step 7: Final Validation)
+- Allows multiple analyses to coexist in drafts/tmp/
+
+**Output:** Analysis file at `drafts/tmp/{block-name}-analysis.md`
+
+---
+
+## Task-Specific Analysis Guidance
+
+### Building a new block
+
+**Must analyze:**
+- Author inputs (list what content authors will provide: e.g., "image, title, description, link")
+  - What's required vs optional?
+  - What can be inferred or auto-generated?
+- What variations do we need to support?
+- Styling and layout expectations
+- Interactive behavior requirements
+- Responsive behavior across viewports
+
+**DON'T design at this stage:**
+- ❌ Table structure (how many columns/rows)
+- ❌ Cell layout (which content goes in which cell)
+- ❌ Block variant classes or naming
+- ❌ Exact authoring format or field names
+- ❌ Authoring experience or ease-of-use (always the goal, addressed in Step 3)
+
+**Note:** At this stage, focus on WHAT content is needed, not HOW it's structured. Detailed content model design (table structure, cells, variants, authoring UX) happens in the content-modeling skill (CDD Step 3).
+
+**Acceptance criteria should cover:**
+- Styling and layout match requirements across viewports
+- All variations work
+- Interactive behavior functions as expected
+
+---
+
+### Adding a Variant to an Existing Block
+
+**Must analyze:**
+- What does the variant do?
+- How does author enable it? (class name? content marker?)
+- Style-only (CSS) or behavior change (JS)?
+- Styling/layout changes for variant
+- Responsive considerations
+
+**Acceptance criteria should cover:**
+- Variant styling/layout matches requirements across viewports
+- Variant applies correctly when specified
+- Existing variants/default behavior continue to function as is
+
+---
+
+### Modify Existing Block Behavior
+
+**Must analyze:**
+- What behavior is changing and why?
+- Any impact to existing content using this block?
+- Content/authoring implications of the change (what content needs to be updated and how)?
+- JS and/or CSS changes needed?
+- Responsive implications?
+
+**Acceptance criteria should cover:**
+- New behavior works as expected
+- Existing functionality is not broken (regression check)
+- Works across viewports
+- Existing content still works
+
+---
+
+### CSS-Only Styling Change
+
+**Must analyze:**
+- What's changing visually
+- Which viewports are affected
+- Layout implications
+
+**Acceptance criteria should cover:**
+- Styling/layout changes match requirements across viewports
+- No layout breaks
+- No regressions
+
+---
+
+### Bug Fix
+
+**Must analyze:**
+- What is the bug?
+- What should happen instead?
+- Root cause (if not obvious)
+
+**Acceptance criteria should cover:**
+- Bug no longer occurs
+- No regressions (existing behavior unchanged)
+- Works across viewports, if relevant
+
+---
+
+## Success Criteria
+
+- ✅ Task type identified (new block, variant, modification, etc.)
+- ✅ Requirements analyzed using appropriate guidance
+- ✅ Acceptance criteria defined
+- ✅ Analysis documented to markdown file
+- ✅ Visual analysis completed (if applicable)
+
+## Output
+
+This skill provides:
+- ✅ Clear understanding of what to build
+- ✅ Documented requirements
+- ✅ Specific acceptance criteria for validation
+- ✅ Analysis notes file for reference
+
+**Next step:** Return to CDD Step 2 with documented analysis and acceptance criteria
+
+---
+
+## Resources
+
+- **Visual Analysis:** `resources/visual-analysis.md` - Comprehensive guide for analyzing screenshots, design files, and existing URLs. Includes systematic analysis techniques, documentation templates, and implementation mapping.