handover

What this skill does

# 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.**

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

```bash
rm -f .claude-plugin/project-config.json
```

---

### Step 1: Ask User for Documentation Type

**MANDATORY:** Use the `AskUserQuestion` tool with EXACTLY these 4 options:

```json
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

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

```bash
# 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

```bash
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:
1. Open a browser for Adobe ID login
2. Capture the IMS OAuth token automatically
3. Save token to `~/.aem/ims-token.json` (user-level, shared across projects)
4. 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:

```javascript
// 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 faste