Project Handover Documentation
Generate comprehensive handover documentation for Edge Delivery Services projects. This skill orchestrates the creation of guides for different audiences.
When to Use This Skill
- "Generate project handover docs"
- "Create handover documentation"
- "Generate project guides"
- "Handover package"
- "Project documentation"
Available Documentation Types
| Guide | Audience | Skill |
|---|
| Authoring Guide | Content authors and content managers | authoring |
| Developer Guide | Developers and technical team | development |
| Admin Guide | Site administrators and operations | admin |
Execution Flow
Step 0: Navigate to Project Root and Verify Edge Delivery Services Project (MANDATORY FIRST STEP)
CRITICAL: You MUST execute this cd command before anything else. Do NOT use absolute paths — actually change directory.
# Navigate to git project root (works from any subdirectory)
cd "$(git rev-parse --show-toplevel)"
# Verify it's an Edge Delivery Services project
ls scripts/aem.js
IMPORTANT:
- You MUST run the
cd command above using the Bash tool
- All subsequent steps operate from project root
- Do NOT use absolute paths to verify — actually navigate
- Guides will be created at
project-root/project-guides/
If scripts/aem.js does NOT exist, respond:
"This skill is designed for AEM Edge Delivery Services projects. The current directory does not appear to be an Edge Delivery Services project (scripts/aem.js not found).
Please navigate to an Edge Delivery Services project and try again."
STOP if check fails. Otherwise proceed — you are now at project root.
Step 0.5: Clean Up Stale Config
Remove any existing config to ensure fresh org and authentication for this project:
rm -f .claude-plugin/project-config.json
Step 1: Ask User for Documentation Type
MANDATORY: Use the AskUserQuestion tool with EXACTLY these 4 options:
AskUserQuestion({
"questions": [{
"question": "Which type of handover documentation would you like me to generate?",
"header": "Guide Type",
"options": [
{"label": "All (Recommended)", "description": "Generate all three guides: Authoring, Developer, and Admin"},
{"label": "Authoring Guide", "description": "For content authors and managers - blocks, templates, publishing"},
{"label": "Developer Guide", "description": "For developers - codebase, implementations, design tokens"},
{"label": "Admin Guide", "description": "For site administrators - permissions, API operations, cache"}
],
"multiSelect": false
}]
})
DO NOT omit any option. All 4 options MUST be presented.
Step 1.5: Get Organization Name (Required Before Generating Guides)
AFTER the user selects guide type(s), but BEFORE invoking any sub-skills, ensure the organization name is available.
1.5.1 Check for Saved Organization
# Check if org name is already saved
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) {}
"
1.5.2 Prompt for Organization Name (If Not Saved)
If no org name is saved, you MUST pause and ask the user directly:
"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."
IMPORTANT RULES:
- DO NOT use
AskUserQuestion with predefined options — ask as a plain text question
- Organization name is MANDATORY — do not offer a "skip" option
- Wait for user to type the org name before proceeding
- If user doesn't provide a valid org name, ask again
1.5.3 Save Organization Name
Once you have the org name, save it so sub-skills can use it:
# Create config directory if needed
mkdir -p .claude-plugin
# Ensure .claude-plugin is in .gitignore (contains project config)
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore
# Save org name to config file
# If "All" was selected, include allGuides flag to skip step 0 in sub-skills
echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
# OR if "All (Recommended)" was selected:
echo '{"org": "{ORG_NAME}", "allGuides": true}' > .claude-plugin/project-config.json
Note: Include "allGuides": true ONLY when user selected "All (Recommended)". This signals sub-skills to skip step 0 validation (orchestrator already validated).
Replace {ORG_NAME} with the actual organization name provided by the user.
Why this matters: The organization name is required by the Helix Admin API to determine if the project is repoless (multi-site). By gathering it once in the orchestrator, sub-skills running in parallel don't each need to prompt the user separately.
Step 1.6: Authenticate with Adobe IMS
AFTER saving the organization name, authenticate to obtain an IMS token.
1.6.1 Check for Existing Auth Token
IMS_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
if (t.imsToken && t.imsTokenExpiry > Math.floor(Date.now()/1000) + 60) {
process.stdout.write(t.imsToken);
}
} catch (e) {}
")
if [ -n "$IMS_TOKEN" ]; then
echo "Token valid"
else
echo "Token missing or expired. Need to authenticate."
fi
1.6.2 Authenticate (If No Valid Token)
If no valid token exists, invoke the auth skill:
Skill({ skill: "project-management:auth" })
This will:
- Open a browser for Adobe ID login
- Capture the IMS OAuth token automatically
- Save token to
~/.aem/ims-token.json (user-level, shared across projects)
- Auto-close the browser when complete
Why authenticate in orchestrator: By authenticating once here, all sub-skills running in parallel can use the saved token without each prompting for login separately.
Step 2: Invoke Appropriate Skill(s)
Based on user selection:
| Selection | Action |
|---|
| All | Invoke all three skills in parallel (see Step 3) |
| Authoring Guide | Skill({ skill: "project-management:authoring" }) |
| Developer Guide | Skill({ skill: "project-management:development" }) |
| Admin Guide | Skill({ skill: "project-management:admin" }) |
Step 3: For "All" Selection
Execute all three guides in PARALLEL with streaming progress updates.
IMPORTANT: Provide immediate feedback to user before starting parallel execution:
"Starting parallel generation of all 3 handover guides:
📄 Authoring Guide - analyzing blocks, templates, configurations...
📄 Developer Guide - analyzing code, patterns, architecture...
📄 Admin Guide - analyzing deployment, security, operations...
You'll see progress updates as each guide moves through its phases."
Launch all three skills simultaneously using parallel Agent tool calls (foreground mode):
In a SINGLE message, invoke three Agent tools in parallel. Foreground agents have full tool permissions and run concurrently:
// All three in ONE message - runs in parallel with full permissions
Agent({
description: "Generate authoring guide",
prompt: "Invoke skill project-management:authoring to generate the authoring guide PDF. Show progress as you complete each phase."
})
Agent({
description: "Generate developer guide",
prompt: "Invoke skill project-management:development to generate the developer guide PDF. Show progress as you complete each phase."
})
Agent({
description: "Generate admin guide",
prompt: "Invoke skill project-management:admin to generate the admin guide PDF. Show progress as you complete each phase."
})
Why foreground agents:
- Run all 3 in parallel (~3x faster than sequential)
- Full tool permissions (Bash, Read, Write, Glob, Skill)
- Progress updates stream as each agent works
When all three complete, report final summary:
"Handover documentation complete:
project-guides/
├── AUTHOR-GUIDE.pdf (full guide for content authors)
├── DEVELOPER-GUIDE.pdf (full guide for developers)
└── ADMIN-GUIDE.pdf (full guide for administrators)
All PDFs generated. Source files cleaned up."
Benefits of parallel execution:
- ~3x faster than sequential execution
- User sees continuous progress updates
- Each guide generates independently
Output Files
| Selection | Output Files |
|---|
| All | project-guides/AUTHOR-GUIDE.pdf, project-guides/DEVELOPER-GUIDE.pdf, project-guides/ADMIN-GUIDE.pdf |
| Authoring Guide | project-guides/AUTHOR-GUIDE.pdf |
| Developer Guide | project-guides/DEVELOPER-GUIDE.pdf |
| Admin Guide | project-guides/ADMIN-GUIDE.pdf |
Note: Each sub-skill generates a PDF only. All source files (.md, .html, .plain.html) are cleaned up after PDF generation.
⚠️ CRITICAL PATH REQUIREMENT
ALL FILES MUST BE SAVED TO project-guides/ FOLDER:
project-guides/AUTHOR-GUIDE.md
project-guides/DEVELOPER-GUIDE.md
project-guides/ADMIN-GUIDE.md
WHY THIS MATTERS: Files must be in project-guides/ for proper organization and PDF conversion.
BEFORE WRITING ANY FILE: Run mkdir -p project-guides first.
MANDATORY RULES
STRICTLY FORBIDDEN:
- ❌ Do NOT read or analyze
fstab.yaml — it does NOT exist in most projects and does NOT show all sites
- ❌ Do NOT create
.plain.html files
- ❌ Do NOT use
convert_markdown_to_html tool
- ❌ Do NOT tell user to "convert markdown to PDF manually"
- ❌ Do NOT say "PDF will be generated later" — each sub-skill generates PDF immediately
- ❌ Do NOT save markdown to root directory or any path other than
project-guides/
REQUIRED:
- ✅ Run
mkdir -p project-guides before writing any files
- ✅ Each sub-skill MUST save markdown to
project-guides/ folder (EXACT PATH)
- ✅ Markdown files MUST have
title and date fields in frontmatter
- ✅ Each sub-skill MUST invoke
project-management:whitepaper to generate PDF immediately after saving markdown
- ✅ Each sub-skill MUST cleanup ALL source files (.md, .html, .plain.html) after PDF generation
- ✅ Final output is
.pdf files ONLY in project-guides/ folder
Related Skills
This skill invokes:
project-management:authoring - Author/content manager guide (generates PDF immediately)project-management:development - Developer technical guide (generates PDF immediately)project-management:admin - Admin operations guide (generates PDF immediately)project-management:whitepaper - PDF generation (invoked by each sub-skill after saving markdown)