原生 → Flutter 遷移
將正在營運的原生應用程式移至單一 Flutter 程式碼庫。此技能採用 先建立文件，再根據文件實作，且僅有獨立審查者核准的內容才能進入下一階段 的方式。假設輸入僅為原生原始碼資料夾。分析文件、PRD、規格與指示文件均由本技能在各階段自動產生。
為何要這樣做
- 兩個應用程式皆在營運中。 遷移後，若現有用戶在登入、付款或儲存資料上有所損失，即為失敗。因此，「不讓任一 OS 用戶遺失功能」是凌駕於所有決策之上的首要原則。
- 原始碼是唯一的真理。 依賴記憶或猜測的值，在實機上必定出錯。所有數值、字串、API、行為都必須附上原始碼的
檔案:行號來源。若無來源，則標註為(推估)。 - 文件必須先達成共識，才能進行並行實作。 若要讓多個模組代理同時工作，它們需要已確定的規格。規格若搖擺不定，會導致同一個畫面需要修改兩次（實際案例中，UI 在功能實作後為了對齊設計而修改了所有畫面 → 此技能在實作前即建立設計規格）。
- 將撰寫者與審查者分離。 不相信實作方的報告，而是由不同上下文背景的審查者直接比對程式碼與規格，核准後才能進入下一階段。
輸入模式
開始時需決定模式。各階段的結構相同，但階段內的任務會有所不同。各模式的差異詳見各參考檔案的「模式專屬」章節。
| 模式 | 輸入 | 核心差異 |
|---|---|---|
| BOTH | iOS 專案 + Android 專案 | 找出 OS 之間的業務與 UI 差異，並統一決定。決定 UI 基準 OS，並管理例外狀況。兩個 OS 的現有用戶均需遷移。 |
| IOS_ONLY | 僅 iOS 專案 | 無需進行差異決定。但若 Android 為新平台，則需設計「新平台空白」（例如返回按鈕、執行時期權限、通知頻道、系統列、App ID、簽署、商店新註冊等）。 |
| ANDROID_ONLY | 僅 Android 專案 | 與上述相反。若 iOS 為新平台，則需設計 Info.plist 權限描述、APNs/entitlements、滑動返回、簽署、描述檔、App Store 新註冊等。 |
即使在單一 OS 模式下，也需另行詢問 Flutter 成果的目標平台（僅原始 OS / 或兩個 OS）。
角色
| 角色 | 由誰擔任 | 負責事項 |
|---|---|---|
| 協調者 | 本會話（我） | 推進階段、指示與彙整代理、修改共用檔案、執行整體測試與建置、向用戶報告。 |
| 撰寫與實作代理 | 子代理（預設 model: opus，用戶可指定其他模型） | 負責其範圍內的分析、文件與程式碼撰寫。 |
| 審查者 | 預設為 model: fable 子代理（獨立上下文）。用戶可連接外部模型（如 GPT、Gemini 等） | 將文件與程式碼直接比對原始碼與規格，進行核准或要求修改。 |
| 用戶 | 決策者 | 決定政策與 UX 選擇、進行實機驗證、處理帳戶、金鑰與商店作業。 |
審查者與共同撰寫規則（僅附加日誌、僅以自身名義核准、雙方核准相同修訂、審查者交接）記載於 references/collaboration.md。與外部模型協作時，由於用戶需傳遞訊息，因此會以檔案為基礎的日誌進行對話。
階段地圖
每個階段都會產出交付物，並需通過關卡才能進入下一階段。進入階段時，需讀取對應的參考檔案。
| # | 階段 | 交付物（位於 <ws>/docs/） | 關卡 | 需讀取的檔案 |
|---|---|---|---|---|
| 0 | 啟動與環境確認 | 00-kickoff.md（模式、目標平台、架構、原則、待決定事項清單） | 用戶確認 | references/00-kickoff.md |
| 1 | 原始碼分析 | analysis/<os>_analysis.md、analysis/api_inventory.md、analysis/screen_inventory.md、(BOTH) analysis/business_diff.md / (單一 OS) analysis/new_platform_gaps.md | 審查者核准 | references/01-analysis.md |
| 2 | PRD | prd.md（決策表 D-編號、API 合約、畫面與功能需求、遷移與安全、階段與關卡、驗收情境）+ logs/prd_log.md | 審查者與我聲明同一修訂完成，並反映用戶決策 | references/02-prd.md |
| 3 | UI 庫存與設計規格 | design/<os>_ui_inventory.md、design_spec.md（標記、元件、資源、字串、各畫面、平台例外、實機驗證清單）、decisions.md（U-編號）+ logs/design_log.md | 各畫面經雙方核准 | references/03-design-spec.md |
| 4 | 實作指示 | impl_plan.md（架構約定、各階段/模組/層級的任務 ID、反向參照表） | 審查者核准，無遺漏項目 | references/04-impl-plan.md |
| 5 | 共用基礎與平台 POC | Flutter 專案、flavor/env、核心（網路、錯誤處理、MVI、設計系統、字串、資源、路由）、平台適配器與外掛程式 | 通過實機 POC | references/05-build.md |
| 6 | 模組實作 | 各模組遵循 data→domain→presentation→test 順序，logs/impl_log.md | 各模組經審查者核准 | references/05-build.md |
| 7 | 整合測試與修正 | 通過所有測試、覆蓋率關卡、建置成功 | 0 失敗 | references/05-build.md |
| 8 | 實機 QA 迴圈 | qa_device_checklist.md、用戶回饋 → U-決策 → 修正 → 文件同步 | 用戶宣告「完成」 | references/06-device-qa.md |
| 9 | 簽署與發佈 | 簽署、描述檔、Firebase、CI、release_runbook.md（新 OS 需新註冊） | 原始 OS：相同 App ID、憑證、更高版本號 / 新 OS：可完成新簽署與上傳 | references/07-release.md |
| 10 | 維護文件 | <flutter>/docs/01~07、README.md | 審查者核准 | references/08-maintenance-docs.md |
若收到跳過階段的請求（例如「分析已做好，從 PRD 開始」），需確認前一階段的交付物是否存在。若無，則告知缺少哪些項目，並依用戶決定進行。若收到的請求是將已實作功能的 Flutter 應用程式調整為原始 UI，則遵循 references/05-build.md 中的「變異路徑」。
必須遵守的原則
這些原則需複製到各階段文件的開頭，讓所有代理以相同標準進行判斷。
- 禁止封鎖現有用戶。 若一個決策導致某一 OS 的用戶無法登入、付款或使用資產，此決策即為錯誤。對於會觸及現有資料的驗證（例如登入格式檢查），標準應從寬；而新的輸入政策應與伺服器一致。
- 預設不進行伺服器端變更。 除非另有指示，否則應在現有 API 合約內解決問題。需要伺服器配合的改進應歸類為「開放問題」。
- 不移植缺陷。 不應因為「等效」而移植原始碼的錯誤。應決定預期結果，並透過回歸測試加以鎖定。若用戶可見的結果會改變，則需將其列入決策清單，請求用戶確認。
- UI 基準 OS（BOTH 模式，遷移期間限定）。 當視覺效果不同時，使用基準 OS 的值。需詢問用戶以哪個 OS 為基準，不預設值。此原則僅作為遷移原始碼期間的判斷標準。遷移完成後（第 10 階段），將改為「當前 Flutter 行為為基準，變更需由用戶決定」。例外情況僅有三種：(a) 遵循基準 OS 會導致另一 OS 用戶無法使用功能或破壞平台特有行為；(b) 基準 OS 行為與 PRD 決策衝突；(c) 基準 OS 的值存在明顯錯誤（保留視覺，僅修正行為）。
- 來源必須明確。 原始碼
檔案:行號。無來源的值標註(推估)，需在實機確認的值標註(實機)，原始碼中不存在而由我們新定義的值標註(新定義)。 - 不引入原始碼中不存在的內容。 不應因為「看起來更好」而引入原始應用程式中沒有的外部 SDK、外部服務或額外設定值（例如商業安全 SDK、通知郵件地址）。應優先移植原始方式；若想更改，需附上理由並詢問用戶。
- 不任意移除可見的文字與功能。 即使原始碼中的提示文字與實際行為不符，也不應刪除，而應詢問用戶（要保留文字，還是要讓行為符合文字）。
- 決策以 ID 記錄。 PRD 決策使用
D-n，用戶 UX 決策使用U-n。當決策變更時，需同步修改程式碼、測試、規格與決策記錄。每個工作輪次結束時，需根據程式碼更新文件。 - 不輸出機密值。 金鑰儲存庫密碼、API 金鑰等機密僅透過檔案傳遞，不在對話或日誌中顯示。哪些檔案應提交至版本控制，需遵循用戶政策（
references/07-release.md）。
代理運作規則
- 範圍所有權。 模組代理僅修改其自身模組的資料夾。若需要修改共用檔案（核心、應用、依賴、資源、字串），代理不得直接修改，而應在最終報告的「共用請求」中提出。由協調者彙整後一次性套用。這是在並行工作中防止衝突最經濟的方法。
- 測試時機。 以序列方式逐一處理模組時，代理需執行其自身模組的測試。以並行批次方式處理多個模組時，代理僅需通過其自身資料夾的
dart analyze，而完整的flutter test與建置則在批次結束後由協調者一次性執行。多個代理同時寫入同一個build/目錄會導致工具崩潰。 - 審查者不信任報告。 審查指示中需包含「不要依賴工作代理的報告，請直接比較程式碼與規格」。審查者不得修改程式碼。
- 簡潔報告。 代理的最終報告應限制行數（範本位於
templates/）。較長的內容應寫入日誌檔案。 - 並行執行。 獨立的分析、模組與文件撰寫工作應一次啟動多個代理呼叫來執行。由於呼叫此技能本身即表示同意進行多代理流程，因此當批次規模較大時，可以使用工作流程工具（例如撰寫→審查→修改管線）。需在開始前以一行文字告知用戶批次規模與使用的模型。
- 恢復。 每個日誌檔案的頂部應有一個進度狀態表，並隨時保持最新。若會話中斷，僅需讀取
00-kickoff.md及各日誌的進度狀態表即可繼續。
需要詢問用戶的事項
以下事項我不自行決定。應簡潔地提出選項與建議方案，並附上理由，然後等待用戶回應。
- 啟動問題清單（
references/00-kickoff.md） - 會影響用戶可見結果的業務差異，以及需要伺服器確認的項目
- UI 基準 OS 及其例外中，會大幅改變功能或視覺效果的項目
- 引入原始碼中不存在的函式庫或服務，或移除原始碼中的功能與文字
- 需要帳戶的作業（Apple Developer、Play Console、Firebase 主控台）、機密值的位置
- 版本控制提交政策、遠端儲存庫是否公開
若用戶回應「照你建議的做」，則將建議方案記錄為決策（U-編號）並繼續進行。
階段結束報告
每個階段結束時，僅向用戶簡短報告以下內容：已建立的文件（路徑）、審查結果（指出問題的數量、已採納/已駁回及原因）、需要用戶決定的事項（含建議方案）、以及下一階段。對於未驗證的事項，需明確標註為未驗證。
參考檔案
| 檔案 | 使用時機 |
|---|---|
references/00-kickoff.md | 開始時 |
references/01-analysis.md | 原始碼分析 |
references/02-prd.md | PRD 撰寫與共識 |
references/03-design-spec.md | UI 庫存與設計規格 |
references/04-impl-plan.md | 實作指示 |
references/05-build.md | 共用基礎、模組實作、整合測試 |
references/06-device-qa.md | 實機 QA 迴圈 |
references/07-release.md | 簽署、flavor、Firebase、CI、發佈 |
references/08-maintenance-docs.md | 維護文件 |
references/collaboration.md | 共同撰寫、審查、交接規則 |
references/pitfalls.md | 實際遷移中發生的問題與預防方法 — 第 5 階段後隨時參考 |
templates/*.md | 代理指示、審查指示、報告格式 |