EXECUTE: Read(file_path=".claude/skills/spec-driven-mcp-converter/references/parameter-extraction.md")
VERIFY: File content loaded (non-empty)
RECORD: N/A

IF conversation contains MCP name/path after /convert-mcp:
  MCP_SOURCE = extracted value
ELSE:
  HALT: AskUserQuestion "Which MCP server do you want to convert? Provide a name, local path, or npm package spec."

IF conversation contains --pattern:
  PATTERN_OVERRIDE = extracted value (api-wrapper | state-based | custom)
ELSE:
  PATTERN_OVERRIDE = null

IF conversation contains --source:
  SOURCE_TYPE = extracted value
ELSE:
  IF MCP_SOURCE starts with "npm:" → SOURCE_TYPE = "npm_package"
  ELIF MCP_SOURCE ends with ".json" → SOURCE_TYPE = "json_schema"
  ELIF MCP_SOURCE is a directory path → SOURCE_TYPE = "local_directory"
  ELSE → SOURCE_TYPE = "local_directory" (default)

IF conversation contains --adapter-script:
  ADAPTER_SCRIPT = extracted value
ELSE:
  ADAPTER_SCRIPT = null

IF conversation contains --output-dir:
  OUTPUT_DIR = extracted value
ELSE:
  OUTPUT_DIR = "./" + MCP_SOURCE name + "-cli"

CONVERT_ID = "CONVERT-" + current timestamp (YYYYMMDD-HHMMSS)
Example: CONVERT-20260319-143000

IF SOURCE_TYPE == "local_directory":
  EXECUTE: Glob(pattern="${MCP_SOURCE}/**/*")
  VERIFY: At least 1 file found
  IF no files: HALT "MCP source directory not found or empty: ${MCP_SOURCE}"

IF SOURCE_TYPE == "json_schema":
  EXECUTE: Read(file_path="${MCP_SOURCE}")
  VERIFY: File content is valid JSON
  IF invalid: HALT "MCP schema file not found or invalid JSON: ${MCP_SOURCE}"

IF SOURCE_TYPE == "npm_package":
  VERIFY: MCP_SOURCE matches pattern "npm:<package>@<version>" or "<package>"
  IF invalid format: HALT "Invalid npm package spec: ${MCP_SOURCE}"

{
  "checkpoint_version": "1.0",
  "convert_id": "${CONVERT_ID}",
  "mcp_source": "${MCP_SOURCE}",
  "source_type": "${SOURCE_TYPE}",
  "pattern_override": "${PATTERN_OVERRIDE}",
  "adapter_script": "${ADAPTER_SCRIPT}",
  "output_dir": "${OUTPUT_DIR}",
  "created_at": "ISO 8601 timestamp",
  "progress": {
    "current_phase": 1,
    "phases_completed": [0],
    "phases_skipped": [],
    "total_phases": 8
  },
  "phases": {
    "00": {"status": "completed"},
    "01": {"status": "pending"},
    "02": {"status": "pending"},
    "03": {"status": "pending"},
    "04": {"status": "pending"},
    "05": {"status": "pending"},
    "06": {"status": "pending"},
    "07": {"status": "pending"}
  }
}

EXECUTE: Write(file_path="devforgeai/workflows/${CONVERT_ID}-convert-checkpoint.json", content=checkpoint)
VERIFY: Glob(pattern="devforgeai/workflows/${CONVERT_ID}-convert-checkpoint.json") returns exactly 1 file

Display:
  "═══ MCP Conversion Workflow Initialized ═══"
  "ID: ${CONVERT_ID}"
  "Source: ${MCP_SOURCE} (${SOURCE_TYPE})"
  "Pattern: ${PATTERN_OVERRIDE || 'auto-detect'}"
  "Output: ${OUTPUT_DIR}"
  "Phases: 8"

EXECUTE: Read(file_path="devforgeai/specs/context/source-tree.md")
EXECUTE: Read(file_path="devforgeai/specs/context/tech-stack.md")
VERIFY: Both files loaded successfully (non-empty content)
RECORD: Update checkpoint phases.01.context_loaded = true

EXECUTE: Evaluate $SOURCE_TYPE from Phase 00
  - "local_directory": Read files from local path
  - "json_schema": Parse JSON schema for tool definitions
  - "npm_package": Use Bash(npm:*) to inspect package
VERIFY: Source type identified and valid
RECORD: Update checkpoint phases.01.source_type = $SOURCE_TYPE

EXECUTE: Invoke code-analyzer subagent (BLOCKING)
  Task: "Analyze MCP server at ${MCP_SOURCE}. Extract all tool definitions including:
         - Tool name
         - Input parameters (name, type, required)
         - Output type
         - Whether tool is async
         - Side effects (state changes)
         - Description
         Return as structured JSON array."
VERIFY: Task result contains 'tools' array with >= 1 tool
RECORD: Update checkpoint phases.01.tool_count = len(tools)

IF tool_count == 0:
  HALT: "No tools found in MCP source. Verify the source path and format."

EXECUTE: For each tool in extracted tools:
  - Verify 'name' field exists and is non-empty string
  - Verify 'inputs' field exists (can be empty dict for no-arg tools)
  - Normalize field names to consistent schema
VERIFY: All tools pass validation
RECORD: N/A (validation is pass/fail)

EXECUTE: Write(file_path="tmp/${CONVERT_ID}/mcp_definition.json", content=normalized_tools_json)
VERIFY: Glob(pattern="tmp/${CONVERT_ID}/mcp_definition.json") returns 1 file
RECORD: Update checkpoint phases.01.tools_extracted = true

Update checkpoint:
  phases.01.status = "completed"
  progress.phases_completed += [1]
  progress.current_phase = 2
Verify checkpoint write via Read()
Display: "Phase 01 Complete: ${tool_count} tools extracted from ${MCP_SOURCE}"

EXECUTE: Read(file_path="tmp/${CONVERT_ID}/mcp_definition.json")
VERIFY: Content is valid JSON with tools array
RECORD: N/A

EXECUTE: For each tool, scan for state indicators:
  - State keywords in tool names: session, connect, navigate, click, page,
    transaction, browser, open, close, destroy, create, cursor, subscribe
  - State keywords in parameter names: session_id, connection_id, context
  - Side effects annotations: browser_state, db_state, file_state
  - Sequential dependencies between tools
  - Async operation markers

  Scoring:
    state_keyword_count = count of state indicators across all tools
    IF state_keyword_count == 0 → detected_pattern = "api-wrapper"
    IF state_keyword_count >= 3 → detected_pattern = "state-based"
    IF 1 <= state_keyword_count < 3 → detected_pattern = "state-based" (with lower confidence)

  IF $PATTERN_OVERRIDE is not null:
    detected_pattern = $PATTERN_OVERRIDE
    confidence = 1.0 (user override)

VERIFY: detected_pattern is one of: "api-wrapper", "state-based", "custom"
RECORD: Update checkpoint phases.02.detected_pattern, phases.02.confidence

EXECUTE: Calculate confidence (0.0 - 1.0):
  - Base confidence from keyword analysis
  - Boost for consistent tool patterns (all stateless or all stateful)
  - Reduce for mixed signals (some stateful, some stateless)
  - Boost for recognized MCP types (puppeteer, postgres, weather known patterns)
VERIFY: Score is a number between 0.0 and 1.0
RECORD: Update checkpoint phases.02.confidence_score

EXECUTE: Build state management profile:
  {
    "stateful": boolean,
    "session_required": boolean,
    "concurrent_sessions": boolean,
    "state_keywords_found": [list],
    "session_model": "ephemeral" | "persistent" | "none"
  }
VERIFY: Analysis object populated
RECORD: N/A

EXECUTE: Generate 3-5 actionable recommendations based on pattern and analysis:
  For api-wrapper: "Use direct 1:1 command mapping", "Add --format flag for output control", etc.
  For state-based: "Use ephemeral session model", "Queue operations within session", etc.
  For custom: "Provide custom adapter script", "Review adapter_api.md for interface", etc.
VERIFY: Non-empty list of recommendations
RECORD: N/A

EXECUTE: IF confidence < 0.7 AND $PATTERN_OVERRIDE is null:
  AskUserQuestion:
    Question: "Pattern detection confidence is ${confidence}. Which pattern best fits your MCP?"
    Options:
      - "api-wrapper" — Stateless API calls, independent commands
      - "state-based" — Stateful operations requiring session management
      - "custom" — Complex/hybrid patterns requiring custom adapter code
VERIFY: User response received OR $PATTERN_OVERRIDE was already set
RECORD: Update checkpoint phases.02.user_override_reason (if user chose)

EXECUTE: Write(file_path="tmp/${CONVERT_ID}/mcp_analysis.json", content={
  "mcp_type": $MCP_SOURCE name,
  "detected_pattern": detected_pattern,
  "confidence": confidence,
  "tools": tools_array,
  "state_management": state_analysis,
  "conversion_recommendations": recommendations
})
VERIFY: Glob(pattern="tmp/${CONVERT_ID}/mcp_analysis.json") returns 1 file
RECORD: Update checkpoint phases.02.analysis_written = true

Update checkpoint:
  phases.02.status = "completed"
  progress.phases_completed += [2]
  progress.current_phase = 3
Verify checkpoint write via Read()
Display: "Phase 02 Complete: Pattern=${detected_pattern}, Confidence=${confidence}"

EXECUTE: Create directories via Write operations:
  - ${OUTPUT_DIR}/
  - ${OUTPUT_DIR}/adapters/
  - ${OUTPUT_DIR}/utils/
  - ${OUTPUT_DIR}/tests/
VERIFY: Glob(pattern="${OUTPUT_DIR}/**/") shows adapters/, utils/, tests/
RECORD: Update checkpoint phases.03.structure_created = true

EXECUTE: Write main CLI script (cli.py) with:
  - argparse with subparsers for each detected tool
  - Tool name → CLI command mapping (snake_case → kebab-case)
  - --format flag (json | text | base64) on each subparser
  - --session flag (for state-based pattern) on tool subparsers
  - Session management subcommands (create, destroy, list) for state-based
  - Error handling with standard Unix exit codes (0-6)
  - Output formatting via utils/output_formatter.py
VERIFY: Glob(pattern="${OUTPUT_DIR}/cli.py") exists
VERIFY: Grep(pattern="argparse", path="${OUTPUT_DIR}/cli.py") confirms CLI framework
RECORD: Update checkpoint phases.03.cli_entry_point = "${OUTPUT_DIR}/cli.py"

IF detected_pattern == "api-wrapper":
  EXECUTE: Write ${OUTPUT_DIR}/adapters/api_wrapper_adapter.py
    - Extends BaseAdapter
    - Implements execute() for stateless tool calls
    - Implements _call_tool() for each MCP tool

IF detected_pattern == "state-based":
  EXECUTE: Write ${OUTPUT_DIR}/adapters/state_based_adapter.py
    - Extends BaseAdapter
    - Session lifecycle (create, destroy, list, get)
    - Session timeout management (default 1 hour)
    - _call_tool_in_session() for each MCP tool
    - State persistence between calls

IF detected_pattern == "custom":
  EXECUTE: Write ${OUTPUT_DIR}/adapters/custom_adapter.py
    - Template with execute() and format_output() methods
    - Placeholder implementations with NotImplementedError
    - IF $ADAPTER_SCRIPT provided: Integrate user's adapter code

VERIFY: Glob(pattern="${OUTPUT_DIR}/adapters/*_adapter.py") returns >= 1 file
RECORD: Update checkpoint phases.03.adapter_type = detected_pattern

IF detected_pattern == "custom":
  EXECUTE: Invoke backend-architect subagent (CONDITIONAL)
    Task: "Review custom adapter template at ${OUTPUT_DIR}/adapters/custom_adapter.py.
           Verify it follows the BaseAdapter interface from adapter-api.md.
           Check error handling and return format compliance."
  VERIFY: Task result confirms adapter is structurally sound
  RECORD: Update checkpoint phases.03.adapter_reviewed = true

EXECUTE: Write ${OUTPUT_DIR}/utils/error_handler.py
  - Standard exit codes: 0=success, 1=general, 2=invalid args, 3=timeout,
    4=resource unavailable, 5=auth failed, 6=rate limited
  - Human-readable error messages on stderr
  - Recovery hints per error type

EXECUTE: Write ${OUTPUT_DIR}/utils/output_formatter.py
  - JSON formatting (default, structured output)
  - Text formatting (human-readable, single values)
  - Base64 formatting (binary data: images, files)

VERIFY: Glob(pattern="${OUTPUT_DIR}/utils/*.py") returns >= 2 files
RECORD: N/A

EXECUTE: Write ${OUTPUT_DIR}/requirements.txt (Python dependencies)
EXECUTE: Write ${OUTPUT_DIR}/README.md (usage instructions, pattern info, examples)
VERIFY: Glob() confirms both files exist
RECORD: N/A

EXECUTE: Write ${OUTPUT_DIR}/tests/test_cli.py with:
  - Test for CLI --help (exit code 0)
  - Test for each command with mock inputs
  - Test for error handling (invalid args → exit code 2)
  - For state-based: test session lifecycle
  - For api-wrapper: test direct command execution
VERIFY: Glob(pattern="${OUTPUT_DIR}/tests/test_*.py") returns >= 1 file
RECORD: N/A

EXECUTE: Count all files in ${OUTPUT_DIR}/ via Glob
VERIFY: Minimum 7 files present (cli.py, adapter, 2 utils, requirements.txt, README.md, test)
RECORD: Update checkpoint phases.03.files_generated = [file list]
RECORD: Update checkpoint phases.03.cli_generation_complete = true

Update checkpoint:
  phases.03.status = "completed"
  progress.phases_completed += [3]
  progress.current_phase = 4
Verify checkpoint write via Read()
Display: "Phase 03 Complete: ${file_count} files generated in ${OUTPUT_DIR}"

EXECUTE: Build frontmatter:
  name: <mcp-name>-cli
  description: (max 1024 chars)
    - Third-person voice
    - Enumerate 3-5 use cases: "(1) ..., (2) ..., (3) ..."
    - Pattern-specific guidance:
      api-wrapper: "Each command is independent - no session needed."
      state-based: "Requires session management - create session before running commands."
      custom: "See documentation for usage patterns."
VERIFY: name matches CLI directory name, description < 1024 chars
RECORD: N/A

EXECUTE: Generate body using pattern-specific template:
  For api-wrapper:
    - ## Direct Usage (each command independent)
    - ## Available Commands (1:1 mapping)
    - ## Output Format (JSON default)
    - ## Error Handling (exit codes)

  For state-based:
    - ## Session Management (create → use → destroy)
    - ## Session Commands (create, destroy, list)
    - ## Available Commands (all require --session)
    - ## Session Lifecycle (timeout, cleanup)
    - ## Output Formats (json, text, base64)

  For custom:
    - ## Usage Overview
    - ## Commands
    - ## Special Features
    - ## Notes

  Use imperative language throughout (NOT "you should" — use "Create a session")
VERIFY: Pattern-specific sections present in generated content
RECORD: N/A

EXECUTE: Write ${OUTPUT_DIR}/skill/SKILL.md (frontmatter + body)
VERIFY: Glob(pattern="${OUTPUT_DIR}/skill/SKILL.md") exists
VERIFY: Grep(pattern="^---", path="${OUTPUT_DIR}/skill/SKILL.md") finds >= 2 YAML delimiters

EXECUTE: Write ${OUTPUT_DIR}/skill/references/cli_reference.md
  - One section per tool with: syntax, parameters, return value, error conditions
VERIFY: Glob() confirms file exists
VERIFY: Grep(pattern="## ", path="${OUTPUT_DIR}/skill/references/cli_reference.md") confirms sections

EXECUTE: Write ${OUTPUT_DIR}/skill/references/usage_examples.md
  - Pattern-specific workflow examples with real commands
VERIFY: Glob() confirms file exists

EXECUTE: Write ${OUTPUT_DIR}/skill/scripts/setup.sh
  - Installation script (pip install, permissions, etc.)
VERIFY: Glob() confirms file exists

EXECUTE: Write ${OUTPUT_DIR}/skill/assets/error_codes.md
  - Exit codes 0-6 with descriptions and recovery strategies
VERIFY: Glob() confirms file exists

EXECUTE: Invoke code-reviewer subagent (BLOCKING)
  Task: "Review the generated skill at ${OUTPUT_DIR}/skill/SKILL.md.
         Check: (1) YAML frontmatter valid, (2) Imperative language - no 'you should/can/need',
         (3) No content duplication between SKILL.md and references,
         (4) Progressive disclosure - details in references not SKILL.md,
         (5) All CLI commands listed, (6) Pattern-specific sections present.
         Return quality score (0-100) and list of issues."
VERIFY: Task result — no CRITICAL/HIGH issues found
RECORD: Update checkpoint phases.04.skill_quality_score = score
RECORD: Update checkpoint phases.04.skill_generation_complete = true

Update checkpoint:
  phases.04.status = "completed"
  progress.phases_completed += [4]
  progress.current_phase = 5
Verify checkpoint write via Read()
Display: "Phase 04 Complete: Skill generated (quality score: ${score}/100)"

EXECUTE: Bash(command="python ${OUTPUT_DIR}/cli.py --help 2>&1")
VERIFY: Exit code 0, output contains subparser/command help text
RECORD: Update checkpoint phases.05.cli_help_ok = true

IF exit code != 0:
  Read the error output. Fix import or syntax issues. Retry once.
  IF still failing after fix: HALT "CLI entry point validation failed"

IF detected_pattern == "api-wrapper":
  EXECUTE: Test one command with mock/sample data
  VERIFY: Command executes without import errors (exit code 0 or 1 acceptable for mock)

IF detected_pattern == "state-based":
  EXECUTE: Test session lifecycle:
    Bash("python ${OUTPUT_DIR}/cli.py session create --name test-session 2>&1")
    Bash("python ${OUTPUT_DIR}/cli.py session list 2>&1")
    Bash("python ${OUTPUT_DIR}/cli.py session destroy --session <id> 2>&1")
  VERIFY: Session create returns ID, list shows session, destroy completes

IF detected_pattern == "custom":
  EXECUTE: Test CLI help for custom commands
  VERIFY: Help displays available commands

RECORD: Update checkpoint phases.05.smoke_test_passed = true/false

EXECUTE: Extract command names from ${OUTPUT_DIR}/skill/SKILL.md via Grep
EXECUTE: Extract subparser names from ${OUTPUT_DIR}/cli.py via Grep
EXECUTE: Compare the two lists — every command in skill must exist in CLI
VERIFY: All commands aligned (no missing commands)
RECORD: Update checkpoint phases.05.interface_aligned = true

EXECUTE: Invoke integration-tester subagent (BLOCKING)
  Task: "Validate alignment between CLI at ${OUTPUT_DIR}/cli.py and
         skill at ${OUTPUT_DIR}/skill/SKILL.md.
         Check: (1) Every command documented in skill exists as CLI subparser,
         (2) Parameter names match between skill docs and CLI argparse,
         (3) Output format documentation matches actual CLI output format,
         (4) Error codes documented in skill match CLI error handling.
         Return alignment score and discrepancies."
VERIFY: Task result indicates alignment (score >= 80%)
RECORD: Update checkpoint phases.05.integration_validation = result

EXECUTE: Bash(command="pytest ${OUTPUT_DIR}/tests/ -v 2>&1") or equivalent
VERIFY: Exit code 0, or expected failures for stub tests
RECORD: Update checkpoint phases.05.tests_executed = true
RECORD: Update checkpoint phases.05.test_results = summary

IF test failures indicate real issues (not stubs):
  Invoke test-automator subagent (CONDITIONAL) to enhance/fix test stubs

EXECUTE: Write(file_path="tmp/${CONVERT_ID}/validation-report.json", content={
  "cli_help_ok": boolean,
  "smoke_test_passed": boolean,
  "interface_aligned": boolean,
  "integration_score": number,
  "tests_executed": boolean,
  "test_results": summary,
  "overall_status": "PASS" | "FAIL" | "PARTIAL"
})
VERIFY: Glob() confirms file exists
RECORD: Update checkpoint phases.05.validation_complete = true

Update checkpoint:
  phases.05.status = "completed"
  progress.phases_completed += [5]
  progress.current_phase = 6
Verify checkpoint write via Read()
Display: "Phase 05 Complete: Validation ${overall_status}"

EXECUTE: AskUserQuestion
  Question: "Register generated skill to .claude/skills/<cli-name>/? This makes the CLI available in future conversations."
  Options:
    - "Yes, register now" — Copy skill to framework directory
    - "No, keep in output directory only" — Skill stays in ${OUTPUT_DIR}/skill/
VERIFY: User response received
RECORD: Update checkpoint phases.06.registration_decision = response

IF user approved registration:
  EXECUTE: Write skill files to .claude/skills/<cli-name>/:
    - SKILL.md
    - references/cli_reference.md
    - references/usage_examples.md
    - scripts/setup.sh
    - assets/error_codes.md
  VERIFY: Glob(pattern=".claude/skills/<cli-name>/SKILL.md") exists
  RECORD: Update checkpoint phases.06.registered = true
  RECORD: Update checkpoint phases.06.skill_path = ".claude/skills/<cli-name>/"
ELSE:
  RECORD: Update checkpoint phases.06.registered = false

EXECUTE: AskUserQuestion
  Question: "Install CLI dependencies now? (pip install -r ${OUTPUT_DIR}/requirements.txt)"
  Options:
    - "Yes, install now"
    - "No, I'll install later"
VERIFY: User response received

IF user chose "Yes":
  EXECUTE: Bash(command="pip install -r ${OUTPUT_DIR}/requirements.txt 2>&1")
  VERIFY: Exit code 0
  RECORD: Update checkpoint phases.06.dependencies_installed = true
ELSE:
  RECORD: Update checkpoint phases.06.dependencies_installed = false

Update checkpoint:
  phases.06.status = "completed"
  progress.phases_completed += [6]
  progress.current_phase = 7
Verify checkpoint write via Read()
Display: "Phase 06 Complete: Registration=${registered}, Dependencies=${installed}"

EXECUTE: Read(file_path="devforgeai/workflows/${CONVERT_ID}-convert-checkpoint.json")
VERIFY: All phases 00-06 have status "completed"
IF any phase incomplete: HALT "Workflow incomplete — phase ${N} not completed"

EXECUTE: Extract from checkpoint:
  - MCP source and type
  - Detected pattern and confidence
  - Files generated count
  - Skill registered (yes/no)
  - Tests passed (yes/no)
  - Integration alignment score
VERIFY: Summary is non-empty with all fields populated
RECORD: N/A

EXECUTE: Write(file_path="devforgeai/workflows/${CONVERT_ID}-conversion-report.md", content=report)
  Report includes: conversion summary, pattern analysis, files generated, validation results,
  registration status, and next steps
VERIFY: Glob() confirms file exists
RECORD: N/A

EXECUTE: Display formatted result:

  ═══════════════════════════════════════
       MCP Conversion Complete
  ═══════════════════════════════════════

  ID:          ${CONVERT_ID}
  Pattern:     ${detected_pattern} (confidence: ${confidence})
  CLI:         ${OUTPUT_DIR}/cli.py
  Skill:       ${OUTPUT_DIR}/skill/SKILL.md
  Registered:  Yes/No
  Tests:       Passed/N/A
  Validation:  ${overall_status}

  ─── Next Steps ───
  1. Run:    python ${OUTPUT_DIR}/cli.py --help
  2. Review: ${OUTPUT_DIR}/skill/SKILL.md
  3. Test:   pytest ${OUTPUT_DIR}/tests/

  Report: devforgeai/workflows/${CONVERT_ID}-conversion-report.md
  ═══════════════════════════════════════

VERIFY: Display shown to user
RECORD: N/A

EXECUTE: Update checkpoint:
  phases.07.status = "completed"
  progress.phases_completed += [7]
  progress.current_phase = "done"
  status = "completed"
  completed_at = ISO 8601 timestamp
VERIFY: Read checkpoint confirms status = "completed"

required_phases = phases_completed + phases_skipped
IF len(required_phases) < 8:
    HALT "WORKFLOW INCOMPLETE — ${len(required_phases)}/8 phases accounted for"
    Display missing phases

Verify: Glob("${OUTPUT_DIR}/cli.*") returns CLI entry point
Verify: Glob("${OUTPUT_DIR}/skill/SKILL.md") returns skill file
Verify: Glob("tmp/${CONVERT_ID}/mcp_analysis.json") returns analysis