lang-migration-samples

lang-migration Skill — Real-World Case Study

This repository is a live demonstration of the lang-migration skill.

It contains both the original Python source project and its complete Go port, produced end-to-end by an AI agent following the skill's six-phase pipeline. Everything in this document is derived from real migration artifacts — no numbers are estimated or fabricated.

中文报告 / Chinese version: README_zh.md

Projects in This Repository

What Is the lang-migration Skill?

The lang-migration skill is an AI-executable workflow for porting an entire open-source project from one programming language to another. It is not a prompt template — it is a structured, multi-session, self-auditing pipeline enforced through five YAML state files and six sequential phases.

P0 Bootstrap → [PGR-0] → P1 Asset Scan → [PGR-1] → P2 Ecosystem Map → [PGR-2]
   → P3 IPO Analysis → [PGR-3] → P4 Translation → [PGR-4] → P5 Verification → [PGR-5]

Core design principles:

The PGR mechanism is the skill's most distinctive feature: **a phase is not complete when the AI says it is complete; it is only complete when an autonomous audit loop produces zero findings and sets passed_at in the YAML.**

Migration At a Glance

All numbers below come directly from [migration_workspace/migration-state.yaml](./migration_workspace/migration-state.yaml) and [migration_workspace/asset-inventory.yaml](./migration_workspace/asset-inventory.yaml).

Scale

Asset Strategy Breakdown (P1)

Ecosystem Mapping (P2)

58 Python ecosystem symbols mapped across three categories:

Note: ultralytics/YOLO is implemented via github.com/yalue/onnxruntime_go (CGO); rapidocr-onnxruntime is replaced by Tesseract. Neither is GAP_ACCEPTED — see Limitations section.

New Go dependencies introduced: 15 packages (see [go-GenericAgent/go.mod](./go-GenericAgent/go.mod)).

On CGO: internal/memory/uidetect calls the ONNX Runtime shared library via github.com/yalue/onnxruntime_go, which requires CGO. The package uses dual build-tag design: default build (go build ./...) compiles to stubs returning ErrCGORequired; building with -tags cgo links onnxruntime.dll/.so for full YOLO inference. Tests are run as go test -tags cgo -count=1 ./....

The Migration Process — Session by Session

The migration ran over 7 active sessions, all tracked in YAML state.

What the Skill Got Right

1. The YAML state files actually worked

Every session started by reading migration-state.yaml. No context was re-established manually. The current_task block told the AI exactly where to resume, including blocked items requiring human input. Across 7 active sessions with the same agent (GitHub Copilot), the migration never had to restart.

2. PGR caught real bugs

The Phase Gate Review mechanism caught two categories of real problems:

Path drift — The AI translated files to structurally-better locations than the inventory predicted. Example:

• frontends/btw_cmd.py → inventoried as internal/frontends/btw/btw.go, actually at internal/frontends/chatcommon/btw.go (merged with related files)
• llmcore.py → inventoried as a single file, actually split into 6 files (client.go, mykey.go, session.go, sse.go, types.go, utils.go) for Go idiom

Anti-cheating mechanism activated — The gap report (migration_workspace/gap-report.yaml) caught that migration-state.yaml claimed 150 assets DONE while asset-inventory.yaml still had 66 entries marked TODO. The PGR forced a full re-audit. This is the "batch fabrication" pattern the skill explicitly guards against.

3. The blocking protocol preserved correctness on ambiguous decisions

Two ecosystem decisions required human approval before proceeding:

• **streamlit → no Go equivalent**: Decided to replace with conductor (HTTP + SSE) rather than embed Python. Required explicit GAP_ACCEPTED sign-off.
• **ultralytics (YOLO) → implemented via ONNX Runtime + CGO**: Initial assessment flagged a behavior gap; human decision approved the ONNX export path (PyTorch model → ONNX → onnxruntime_go + CGO), preserving full detection capability under -tags cgo builds. confirmed_by: human.

Both decisions are logged in [migration_workspace/ecosystem-map.yaml](./migration_workspace/ecosystem-map.yaml) with confirmed_by: human.

4. The "no mock" policy found two real production bugs

Bug 1 — Goroutine leak (P5 integration tests):

// internal/agent/agent.go — BEFORE fix
go func() {
    // ... LLM streaming loop
    // streamCh was NEVER closed → for-select in caller blocked forever after loop ended
}()

Fix: defer close(streamCh). A mock test would have closed the channel itself and never exposed this.

**Bug 2 — Package init() panic** (P5 unit tests):

continue_cmd.go contained a PCRE lookahead (?=^===...) in a package-level regexp.MustCompile. Go's RE2 engine doesn't support lookaheads — the program panicked at startup, failing all 13 chatcommon tests. Fix: replaced with a line-by-line scanner (behavioral equivalence). This bug passed P4 compilation but was caught by P5 test execution — validating that PGR requires tests to actually run.

5. Structural equivalence produced idiomatic Go

The IPO analysis (P3) documented algorithm steps explicitly, which meant the Go translation preserved loop structure and control flow. The result is Go code that reads naturally — not "Python in Go syntax."

Example architectural decisions from IPO analysis:

• MixinSession multi-backend failover with springSec=300 spring-back to primary
• History lives in backend.history, not in messages slice (mirrors Python design)
• ToolClient (text-protocol) vs NativeToolClient (native function calling) preserved as separate types

What the Skill Didn't Cover — Honest Limitations

ML/CV: Ecosystem substitution, not gaps

The three Python ML/CV modules are handled differently — not all are missing:

True GAP_ACCEPTED items (no implementation):

MINOR_DEVIATION: Two behavioral differences from source

Both deviations are documented in [go-GenericAgent/MIGRATION_NOTES.md](./go-GenericAgent/MIGRATION_NOTES.md) with justification. Neither affects correctness.

The skill requires sustained human attention

The migration required approximately 7 active sessions of human supervision. While the YAML state files handled continuity, the human had to:

• Approve GAP_ACCEPTED decisions (2 critical ones)
• Unblock path-drift discrepancies discovered during PGR
• Review retrospective entries after bug fixes

This is not a "one prompt, done" tool. It is a structured collaboration protocol.

Translated Module Summary

Frontends (internal/frontends/): conductor (HTTP+SSE), telegram, feishu, discord, dingtalk, wecom, qq, tui (bubbletea), chatcommon (4 files merged), acp, desktoppet (Win32 reimplementation), wechat (GAP_ACCEPTED placeholder)

Memory subsystems (internal/memory/): keychain, adbui, procmem (Windows), ljqctrl (Windows), sessions, vision, skillsearch, autonomous, ocr (Tesseract), uidetect (ONN