/extract

command: extract
disable-model-invocation: true
description: "Design System & Product Reverse-Engineering - Extract tokens, components, architecture, and PRDs from codebases or live products"
aliases:
  - reverse-engineer
  - analyze-codebase

/octo:extract - Design System & Product Reverse-Engineering

**Your first output line MUST be:** `🐙 Octopus Extract`

🤖 INSTRUCTIONS FOR CLAUDE

When the user invokes this command (e.g., `/octo:extract <target>` or `/octo:extract <target>`):

Step 0: PDF Page Selection (if target is PDF)

**CRITICAL: For PDF files > 10 pages, ask user which pages to extract:**

// Check if target is a PDF file
if (target.endsWith('.pdf') && isFile(target)) {
  // Use Claude Octopus PDF page selection utility
  const pageCount = await getPdfPageCount(target);

  if (pageCount > 10) {
    console.log(`📄 Large PDF detected: ${pageCount} pages`);
    console.log(`Reading all pages may use ${pageCount * 750} tokens (~${Math.ceil(pageCount/133)} API calls).`);

    const selection = await AskUserQuestion({
      questions: [{
        question: `This PDF has ${pageCount} pages. Which pages would you like to extract?`,
        header: "PDF Pages",
        multiSelect: false,
        options: [
          {label: "First 10 pages", description: "Quick overview (pages 1-10)"},
          {label: "Specific pages", description: "Enter custom page range"},
          {label: "All pages", description: `Full document (~${Math.ceil(pageCount/133)} API calls)`}
        ]
      }]
    });

    let pageParam = "";
    if (selection === "First 10 pages") {
      pageParam = "1-10";
    } else if (selection === "Specific pages") {
      pageParam = await askForInput("Enter page range (e.g., 1-5, 10, 15-20):");
    }
    // else "All pages" - use empty string

    // Store for use in extraction phases
    target = { path: target, pages: pageParam };
    console.log(`✓ Will extract pages: ${pageParam || 'all'}`);
  }
}

**Example output:**

📄 Large PDF detected: 45 pages
Reading all pages may use 33,750 tokens (~34 API calls).

┌─────────────────────────────────────────────────────────┐
│ This PDF has 45 pages. Which pages would you like to   │
│ extract?                                                 │
│                                                          │
│ ● First 10 pages                                        │
│   Quick overview (pages 1-10)                           │
│                                                          │
│ ○ Specific pages                                        │
│   Enter custom page range                               │
│                                                          │
│ ○ All pages                                             │
│   Full document (~34 API calls)                         │
└─────────────────────────────────────────────────────────┘

✓ Will extract pages: 1-10

Step 1: Validate Input & Check Dependencies

**Parse the command arguments:**

# Expected format:
# /octo:extract <target> [options]
# target: URL or local directory path
# options: --mode, --scope, --depth, --output, --storybook, --ignore

**Check Claude Octopus availability with the Bash tool.** Run the shared live readiness check because extraction may use an external provider:

OCTO_ROOT="${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}"
provider_helper="$OCTO_ROOT/scripts/helpers/check-providers.sh"
if [[ ! -x "$provider_helper" ]]; then
  echo "ERROR: Claude Octopus provider readiness helper is unavailable. Run /octo:setup." >&2
  exit 1
fi

PROVIDER_STATUS="$(OCTOPUS_PREFLIGHT_PROBE=1 "$provider_helper" 2>/dev/null || true)"
printf '%s\n' "$PROVIDER_STATUS"

READY_EXTERNAL="$(printf '%s\n' "$PROVIDER_STATUS" |
  awk -F: '$1 !~ /^claude($|-)/ && $2 == "available" { print $1 }')"
if [[ -z "$READY_EXTERNAL" ]]; then
  echo "No external provider is ready. Continuing extraction with Claude only."
  echo "Run /octo:setup to configure an external provider."
fi

Treat the emitted `provider:status` lines and `READY_EXTERNAL` as authoritative. Do not re-detect binaries or credentials inside this command.

Step 2: Intent Capture (Interactive Questions)

**CRITICAL: Use AskUserQuestion to gather extraction intent:**

AskUserQuestion({
  questions: [
    {
      question: "What do you want to extract from this codebase/URL?",
      header: "Extract Mode",
      multiSelect: false,
      options: [
        {label: "Design system only", description: "Tokens, components, Storybook scaffold"},
        {label: "Product architecture only", description: "Architecture, features, PRDs"},
        {label: "Both (Recommended)", description: "Complete design + product documentation"},
        {label: "Auto-detect", description: "Let Claude decide based on what's found"}
      ]
    },
    {
      question: "Who will use these extraction outputs?",
      header: "Audience",
      multiSelect: true,
      options: [
        {label: "Designers", description: "Need design tokens and component inventory"},
        {label: "Frontend Engineers", description: "Need Storybook and component docs"},
        {label: "Product/Leadership", description: "Need architecture maps and PRDs"},
        {label: "AI Agents", description: "Need structured, implementation-ready outputs"}
      ]
    },
    {
      question: "What should be the source of truth?",
      header: "Source Priority",
      multiSelect: false,
      options: [
        {label: "Code files (Recommended)", description: "Extract from codebase directly"},
        {label: "Live UI rendering", description: "Analyze computed styles from browser"},
        {label: "Both - prefer code", description: "Use code when available, infer from UI otherwise"}
      ]
    },
    {
      question: "What extraction depth do you need?",
      header: "Depth",
      multiSelect: false,
      options: [
        {label: "Quick (< 2 min)", description: "Basic token/compo