adobe/handover-developer

Project Handover - Development

Generate a complete technical guide for developers. Analyzes the codebase and produces actionable documentation that enables developers to understand, maintain, and extend the project.

---

Step 0: Navigate to Project Root (CONDITIONAL)

Skip if allGuides is set in .claude-plugin/project-config.json (orchestrator already validated).

ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { console.log(JSON.parse(d).allGuides ? 'true' : ''); } catch(e) { console.log(''); }
")
if [ -z "$ALL_GUIDES" ]; then
  cd "$(git rev-parse --show-toplevel)"
  ls scripts/aem.js
fi

If scripts/aem.js does not exist, tell the user this skill requires an AEM Edge Delivery Services project and stop.

All subsequent steps operate from project root. Guides are created at project-guides/.

---

Execution Checklist

- [ ] Phase 0: Get org name and authenticate
- [ ] Phase 1: Gather project information
- [ ] Phase 2: Analyze project architecture
- [ ] Phase 3: Document design system
- [ ] Phase 4: Document blocks, models, and templates
- [ ] Phase 5: Generate PDF

---

Phase 0: Get Organization Name and Authenticate

0.1 Check for Saved Organization

cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { const o = JSON.parse(d).org; if(o) console.log('org: ' + o); } catch(e) {}
"

0.2 Prompt for Organization Name (If Not Saved)

If no org name is found, ask the user:

"What is your Config Service organization name? This is the {org} part of your Edge Delivery Services URLs (e.g., https://main--site--{org}.aem.page). The org name may differ from your GitHub organization."

Ask as a plain text question — not AskUserQuestion with options. Organization name is mandatory.

0.3 Save Organization Name

mkdir -p .claude-plugin
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

if [ -f .claude-plugin/project-config.json ]; then
  cat .claude-plugin/project-config.json | sed 's/"org"[[:space:]]*:[[:space:]]*"[^"]*"/"org": "{ORG_NAME}"/' > /tmp/project-config.json && mv /tmp/project-config.json .claude-plugin/project-config.json
else
  echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
fi

Replace {ORG_NAME} with the actual organization name.

0.4 Check Auth Token

AUTH_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
      process.stdout.write(t.authToken);
    }
  } catch (e) {}
")

if [ -z "$AUTH_TOKEN" ]; then
  echo "AUTH_REQUIRED"
fi

If AUTH_REQUIRED, invoke the auth skill:

Skill({ skill: "aem-project-management:auth" })

---

Phase 1: Gather Project Information

1.1 Get Project URLs and Repository

git remote -v | head -1
git branch -a | head -10

Extract: repository owner, repo name, main branch name.

1.2 Check Configuration Method

ls helix-config.yaml 2>/dev/null && echo "Uses legacy helix-config" || echo "Uses Config Service (modern)"

1.3 Fetch Sites via Config Service API

The Config Service API is the only reliable source for site information. Do not use fstab.yaml, README, or git remote URLs.

ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")
AUTH_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    process.stdout.write(t.authToken || '');
  } catch (e) {}
")

curl -s -H "x-auth-token: ${AUTH_TOKEN}" -H "Accept: application/json" \
  "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json

node -e "
  const d = require('fs').readFileSync('.claude-plugin/sites-config.json', 'utf8');
  const j = JSON.parse(d);
  if (!j.sites || !j.sites.length) {
    console.error('No sites returned — verify org name and re-authenticate if needed');
    process.exit(1);
  }
  console.log('Found ' + j.sites.length + ' site(s): ' + j.sites.map(s => s.name).join(', '));
"

If validation fails, verify the org name is correct, re-authenticate, and retry.

Fetch per-site config:

curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

Extract: code.owner, code.repo, content.source.url, content.source.type.

Multiple sites = repoless setup. Single site = standard setup. Record this — it affects the aem up local dev instructions.

1.4 Check Node.js Requirements

cat .nvmrc 2>/dev/null || cat package.json | grep -A2 '"engines"'

---

Phase 2: Analyze Project Architecture

Read site config:

cat .claude-plugin/sites-config.json

2.1 Map Project Structure

ls -la && ls -la blocks/ && ls -la scripts/ && ls -la styles/
ls -la templates/ 2>/dev/null || echo "No templates folder"

2.2 Identify Boilerplate vs Custom Files

Only document files that were actually customized.

git log --oneline --follow {file_path} | head -5
git log --format="%an - %s" --follow {file_path} | head -5

| Git History | Action | |-------------|--------| | Only "Initial commit" | Skip — boilerplate default, never worked on | | Only aem-aemy[bot] commits | Skip — auto-generated | | Multiple commits by team | Document — customized |

2.3 Analyze scripts/aem.js (Core Library)

grep -E "^export" scripts/aem.js

Document which functions the project imports from aem.js (e.g., sampleRUM, loadHeader, loadFooter, decorateBlock, loadBlock, loadCSS).

2.4 Analyze scripts/scripts.js

grep -E "^import|^export|^function|^async function|buildAutoBlocks|loadTemplate|getLanguage|getSiteRoot|decorateMain|loadEager|loadLazy|loadDelayed" scripts/scripts.js

Document:

| Pattern | What to Document | |---------|-----------------| | import statements | What it imports from aem.js and utils.js | | loadEager / loadLazy | Any custom logic added to E-L-D phases | | buildAutoBlocks | Auto-blocking logic | | loadTemplate / template handling | Template system | | getLanguage / language detection | Multi-language setup | | getSiteRoot / site detection | Multi-site configuration | | External script loading | Which phase — flag if in eager (performance risk) |

2.5 Analyze scripts/delayed.js

grep -E "^import|function|google|analytics|gtag|alloy|martech|OneTrust|launch|chatbot|widget" scripts/delayed.js

Document analytics integrations, marketing tools, performance monitoring. Confirm no render-critical code is in this file.

2.6 Check for Utility Functions

grep -E "^export|^function" scripts/utils.js 2>/dev/null || echo "No utils.js"
ls scripts/*.js
grep -rl "utils.js" blocks/ scripts/ 2>/dev/null

Document shared utility functions and which blocks/scripts import them.

2.7 Check for External Dependencies

grep -A 20 '"dependencies"' package.json 2>/dev/null | head -25
grep -r "cdn\|unpkg\|jsdelivr" scripts/ blocks/ --include="*.js" 2>/dev/null

---

Phase 3: Document Design System

3.1 Extract CSS Custom Properties

grep -E "^\s*--" styles/styles.css

Organize into categories: Typography, Colors, Spacing, Layout.

3.2 Document Font Setup

grep -E "@font-face|font-family|font-weight|src:" styles/fonts.css 2>/dev/null
ls fonts/ 2>/dev/null

Document: font files and formats, family names, weights, fallback fonts.

3.3 Document Breakpoints

grep -E "@media.*min-width|@media.*max-width" styles/styles.css | sort -u

Standard breakpoints: Mobile < 600px, Tablet 600-899px, Desktop 900px+, Large 1200px+. Document any deviations.

3.4 Document Section Styles

grep -A 5 "\.section\." styles/styles.css
grep -A 5 "\.section\[" styles/styles.css

---

Phase 4: Document Blocks, Models, and Templates

Boilerplate Filtering

Run silently — do not show output to user.

• Include: Items with 2+ commits and at least one after "Initial commit"
• Exclude: Items with only "Initial commit" or only aem-aemy[bot] commits

4.1 Identify and Analyze Customized Blocks

head -30 blocks/{blockname}/{blockname}.js
grep -E "^\." blocks/{blockname}/{blockname}.css | head -30
grep -E "classList\.contains|classList\.add" blocks/{blockname}/{blockname}.js

Document for each customized block:

| Field | What to Record | |-------|----------------| | Name | Block folder name | | Purpose | What it does | | DOM Input | Expected HTML structure from CMS | | DOM Output | Transformed structure after decoration | | Variants | CSS classes that modify behavior | | Dependencies | External libraries, other blocks, utils |

4.2 Document Universal Editor Models (If Customized)

Apply boilerplate filtering to models/*.json. Exclude standard boilerplate models (_page.json, _section.json, _button.json, _image.json, _text.json, _title.json) if unchanged. Skip section if all models are boilerplate.

4.3 Document Customized Templates

Apply boilerplate filtering to templates/*/. For each customized template, document purpose, how it's applied (template: name in metadata), and what it changes.

---

Phase 5: Generate Developer Guide

5.1 Output File

Save to project-guides/DEVELOPER-GUIDE.md (run mkdir -p project-guides first).

Read resources/developer-guide-template.md for the full document structure. Fill in all sections using data gathered in Phases 1–4 — replace every [placeholder] with actual project values.

5.2 Convert to Professional PDF

Save the completed markdown to project-guides/DEVELOPER-GUIDE.md with YAML frontmatter (title, date using full date format e.g., "February 17, 2026"). Then immediately invoke PDF conversion:

Skill({ skill: "aem-project-management:whitepaper", args: "project-guides/DEVELOPER-GUIDE.md project-guides/DEVELOPER-GUIDE.pdf" })

The whitepaper skill auto-cleans source files. Final output: project-guides/DEVELOPER-GUIDE.pdf.

Inform the user: "Developer guide complete: project-guides/DEVELOPER-GUIDE.pdf"

---

Success Criteria

| Category | Check | |----------|-------| | Data Source | Config Service API called (https://admin.hlx.page/config/{ORG}/sites.json) | | Data Source | Site list from API response, not fstab.yaml or codebase analysis | | Data Source | Repoless/standard determination from Config Service, not inferred from code | | Content | Quick Reference with all project URLs | | Content | Architecture overview accurate to project | | Content | Design system fully documented (tokens, fonts, breakpoints) | | Content | Project-specific blocks documented | | Content | Custom scripts.js functions documented | | Content | delayed.js integrations documented | | Content | Templates documented (if applicable) | | Content | Local development setup verified | | Content | Common tasks have clear instructions | | Content | Troubleshooting section covers common issues | | Output | PDF generated at project-guides/DEVELOPER-GUIDE.pdf | | Output | All source files cleaned up (only PDF remains) |

---

Communication: Never use "EDS" as an acronym — always write "Edge Delivery Services" or "AEM Edge Delivery Services" in all output and documentation.