cli-to-go-migration

CLI to Go Migration Skill

This skill guides the end-to-end (E2E) migration of a command-line interface (CLI) tool from any source language (e.g., TypeScript/Node, Python, Ruby) to Go. Use it to minimize runtime dependencies, maximize native performance, ensure filesystem security, and write robust, multi-platform binaries.

Migration Pipeline Overview

The migration follows nine sequential phases. Each phase requires specific human-AI coordination. Explicit breakpoints are defined where the AI agent must stop and prompt the user for validation.

graph TD
    P0[Phase 0: Intake & Suitability Research] -->|Breakpoint: Suitability Approval| P1[Phase 1: Grounding via Go Skills]
    P1 --> P2[Phase 2: Architecture & Goals]
    P2 --> P3[Phase 3: Configuration & Path Mapping]
    P3 --> P4[Phase 4: Test-First TDD & Error Rules]
    P4 --> P5[Phase 5: Concurrency via Subagents]
    P5 -->|Breakpoint: Scan Hangs| P6[Phase 6: Package Layout & CI Matrix]
    P6 -->|Breakpoint: CI Matrix Omissions| P7[Phase 7: Error Cleanup Audit]
    P7 --> P8[Phase 8: Release Attestation & Signing]
    P8 -->|Breakpoint: Gatekeeper/SmartScreen| End[Completed Zero-Dependency Go CLI]

Phase 0: Intake and Suitability Research

Before initiating any migration, research the target codebase to verify if the proposed language is a suitable replacement.

1. Identify User Goals: Ask the user to specify the location of the codebase to migrate, define their target performance/security/maintenance metrics, and describe core use cases.
2. Review Stack Alternatives: Proactively audit alternative target stacks based on development complexity, language rules friction, runtime distribution overhead, and ecosystem support. Use a generalized prompt pattern:
   • Identify alternative stacks:

     Research online and identify 3-5 stack alternatives to use over [current stack] and explain why (e.g., performance, security) with specific examples and links
     

3. Lock in Target Stack: Check for prior work and research target-specific idioms:
   • Prior work check:

     I want to port [tool/repository] to [target language]. Did anyone do this before?
     

   • Target idioms and patterns check:

     Identify 3-5 patterns on how to / how NOT use [target language] and explain them to me
     

4. Analyze the source stack:
   • Inspect the codebase dependencies (e.g., scan package manifests like package.json or requirements.txt) to assess dependency overhead and vulnerability vectors.
   • Evaluate startup latency requirements. If the tool is invoked frequently in scripts (like shell tools) where startup latency must be sub-10ms, compiled binaries are highly suitable.
5. Present Suitability Report: Stop and present a brief suitability evaluation comparing package size, startup speed, readability-by-strangers, and complexity tradeoffs. Do not proceed without user approval.