onboarding

name	onboarding
description	Run post-install setup for the drupal-sdlc plugin. Auto-detects project values, verifies gh CLI and MCP connectivity. Use after installing the plugin on a new project, or when MCPs show as failed.
argument-hint	(no arguments needed)

Plugin Onboarding

Run all setup checks, auto-detect project values, and fix what's missing. Go through every check in order.

Telemetry

f=$(ls ~/.claude/plugins/cache/*/drupal-sdlc/*/hooks/send-metric.sh 2>/dev/null | head -1); [ -n "$f" ] && bash "$f" "drupal-sdlc:onboarding" 2>/dev/null; true

Run this first — do not show output to user.

Setup Mode Detection

!`grep -c "## Drupal SDLC Workflow" CLAUDE.md 2>/dev/null || echo "0"`

!`test -f drupal-claude.yml && echo "LEGACY_YAML_EXISTS" || echo "NO_LEGACY_YAML"`

• Count = 0: FIRST USER setup
• Count > 0: TEAM MEMBER setup (skip Checks 6a and 7)
• drupal-claude.yml exists: MIGRATION — read values from it instead of auto-detecting

Instructions

Report each check as:

• Pass: Check N — Name: one-line result
• Fail: Check N — Name: what's wrong + exact fix

---

Check 0 — Node.js version (BLOCKER)

node --version 2>/dev/null || echo "NOT FOUND"

Must be 18+. If below 18 or missing: STOP. Tell user to install Node.js 18+ (nvm or nodejs.org), restart Claude Code, re-run onboarding.

---

Check 1 — gh CLI authentication (BLOCKER)

gh auth status 2>&1

If not authenticated: tell user to run gh auth login. Continue with remaining checks.

---

Check 2 — .mcp.json at project root

cat .mcp.json 2>/dev/null | head -1 || echo "NOT FOUND"

If missing: find plugin template at ~/.claude/plugins/cache/drupal-sdlc-plugin/drupal-sdlc/*/templates/mcp.json and copy it, or create with:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Tell user to commit .mcp.json to git.

---

Check 3 — enableAllProjectMcpServers

cat .claude/settings.local.json 2>/dev/null | grep -c enableAllProjectMcpServers || echo "0"

If missing: add "enableAllProjectMcpServers": true to .claude/settings.local.json (create if needed). Tell user to restart Claude Code.

---

Check 4 — Playwright MCP connectivity

Test if Playwright MCP tools (browser_navigate, browser_take_screenshot) are available.

If unavailable: likely needs a Claude Code restart after Checks 2-3.

---

Check 5 — Atlassian MCP connectivity + OAuth

Use Atlassian MCP atlassianUserInfo to verify.

If fails: tell user to reconnect Atlassian MCP via Claude Code Settings > MCP Servers.

---

Check 6 — Auto-detect project values

Skip for TEAM MEMBER setup. Jump to Check 6b.

Check 6a — FIRST USER: Auto-detect

Drush prefix:

if [ -d ".ddev" ]; then echo "ddev drush"; elif [ -f ".lando.yml" ]; then echo "lando drush"; elif [ -f ".docksal/docksal.env" ]; then echo "fin drush"; else echo "drush"; fi

Quality command:

P=""; if [ -d ".ddev" ]; then P="ddev"; elif [ -f ".lando.yml" ]; then P="lando"; fi; if grep -q '"quality"' composer.json 2>/dev/null; then echo "$P composer run-script quality"; elif [ -f "grumphp.yml" ] || [ -f "grumphp.yml.dist" ]; then echo "$P exec vendor/bin/grumphp run"; else echo "not detected"; fi

GitHub owner/repo:

git remote get-url origin 2>/dev/null | sed 's|.*github\.com[:/]\([^/]*\)/\([^.]*\).*|owner: \1\nrepo: \2|'

Entity types (if site is running):

DRUSH="drush"; if [ -d ".ddev" ]; then DRUSH="ddev drush"; elif [ -f ".lando.yml" ]; then DRUSH="lando drush"; fi
$DRUSH entity:bundles --entity-type=node 2>/dev/null || echo "Site not running — detected later"
$DRUSH entity:bundles --entity-type=taxonomy_term 2>/dev/null

MIGRATION MODE: If drupal-claude.yml exists, read values from it instead.

Jira cloud ID: Use Atlassian MCP getAccessibleAtlassianResources. If one site, use it; if multiple, ask user to pick.

Present detected values and ask for confirmation before proceeding.

---

Check 7 — CLAUDE.md generation

Skip for TEAM MEMBER setup.

If CLAUDE.md does not exist: tell user to run /init first, then re-run onboarding. STOP.

If CLAUDE.md exists but lacks "## Drupal SDLC Workflow": APPEND the following (do NOT overwrite /init content):

---

## Drupal SDLC Plugin Configuration

- **GitHub:** {detected_owner}/{detected_repo}
- **Jira cloud ID:** {detected_jira_cloud_id}
- **Drush prefix:** `{detected_drush_prefix}`
- **Quality command:** `{detected_quality_command}`

## Trigger Command
To start the full workflow:

work on jira ticket KEY-X

## AI Guardrails
- NEVER modify files not required by the current task
- Always show a diff before changes
- Always state risk level: Low / Medium / High
- NEVER write UUID values in config YAML

## Protected Files — NEVER modify without explicit approval
- web/sites/default/settings.php
- web/sites/default/settings.ddev.php
- *.install files
- config_split.config_split.*.yml

## Config Management — ALWAYS follow this order
1. {drush_prefix} config:import -y
2. {drush_prefix} config:export -y
3. {drush_prefix} config:status (must show "No differences")
Always commit post-export files — never hand-written config YAML.

## Known Pitfalls
1. Never hand-craft UUIDs in config YAML — config:export adds them.
2. Never write inline login in Playwright tests — use loginAsAdmin() from helpers/auth.ts.
3. Always run config:export after config:import — commit exported version.
4. Save screenshots to tests/playwright/test-results/screenshots/.
5. Never use #edit-submit — use getByRole('button', { name: 'Save' }).
6. CKEditor body field — use page.getByRole('textbox', { name: 'Rich Text Editor' }).
7. Always post PR link back to Jira.
8. Jira Done transition is automatic — GitHub Action handles it on merge.

MIGRATION MODE: After success, tell user to delete drupal-claude.yml.

If CLAUDE.md already contains SDLC sections: Pass. Continue.

---

Summary

Show this table after all checks:

Check	Status	Action needed
Node.js 18+	pass/fail	—
gh CLI auth	pass/fail	—
.mcp.json	pass/created	—
enableAllProjectMcpServers	pass/set	—
Playwright MCP	pass/fail	—
Atlassian MCP	pass/fail	—
Project detection	pass/confirmed	—
CLAUDE.md	pass/appended	—

If files were created/changed: Tell user to restart Claude Code and re-run. If all pass (FIRST USER): Commit .mcp.json and CLAUDE.md. Tell team to run /drupal-sdlc:onboarding. If all pass (TEAM MEMBER): Ready to work on jira ticket KEY-X.

Hard Rules

• Run every check in order — do not skip
• For CLAUDE.md — user runs /init first, then onboarding APPENDS SDLC sections
• Never overwrite CLAUDE.md content generated by /init
• Auto-detect all project values — never ask user to fill in config files
• Present detected values for confirmation before using them
• Always tell user to commit .mcp.json and CLAUDE.md to git