dadamsuk/slipdock-work

從 slipdock 開始工作

看板是唯一計劃記錄：包含接下來要做什麼，以及發生過的事情的記錄。伺服器會記錄自己的慣例 — 請先閱讀，每個會話一次，然後再選擇或更新任何內容：

slipdock guide                    # 從 GET /api/guide 取得的 Markdown

如果此機器上沒有 CLI（這是常見情況，因為 CLI 需要 Elixir）：

B="${SLIPDOCK_URL:-$(cat ~/.config/slipdock/url 2>/dev/null)}"   # 如果兩者都沒有設定，請詢問使用者
curl -s -H "Authorization: Bearer $SLIPDOCK_TOKEN" "$B/api/guide"

伺服器的位址來自 $SLIPDOCK_URL，否則來自 ~/.config/slipdock/url（由 slipdock url 或伺服器的 /install.sh 寫入）。如果你兩者都沒有，請向使用者詢問他們的 Slipdock 位址，而不是自己猜測一個 — 託管看板類似於 https://app.slipdock.us，自託管的則是你用來訪問它的任何名稱。

傳遞 token（如果有的話）（$SLIPDOCK_TOKEN，否則為 ~/.config/slipdock/token）。指南不需要 token，但使用 token 時，它會以使用者的實際看板、每個看板上的列表、以及哪個列表是準備清單、待辦事項清單、進行中工作清單和已完成工作清單作為結尾 — 這正是你需要用來挑選工作的資訊。

指南的優先級高於此檔案。 它來自運行的伺服器，因此是最新的：其中的端點、詞彙和看板佈局是在請求時產生的。此檔案僅告知你去取得它，以及在尚未取得時該怎麼做。

尋找沒有人能命名的東西

slipdock cards <board> --search Q 按子字串過濾一個看板。它的其他過濾器不是詢問文字，而是詢問狀態，並且它們能回答「我應該選擇什麼」：--deps ready 排除等待未完成卡片的項目，--no-assignee 排除其他人的工作，--due overdue 找出已逾期的項目。因此，符合資格的清單只需一次呼叫：

slipdock cards <board> --column "To Do" --open --deps ready --no-assignee

slipdock search <words...> 則不同：它根據含義進行匹配，跨越使用者能看到的所有看板，並且涵蓋評論和狀態更新以及卡片。當使用者描述一件事而不是命名它時（「關於退款無條件進位問題的卡片」）、當你想要的東西可能出現在評論而不是標題中時，或者當你不知道該看哪個看板時，請使用它。閱讀它列印的匹配片段，然後在修改之前使用 slipdock card <id> 取得整張卡片的內容。

它將詳細說明的簡短版本

• 史詩和子卡片。 頂層卡片是史詩：一個成果，包含優先級、日期和討論。工作存在於其子卡片中，每個子卡片對應一個任務。核對清單項目是任務內部的步驟。你發現的新工作應作為子卡片放在它所服務的史詩之下 — 而不是作為新的頂層卡片。
• 選擇。 完成已在進行的工作；然後處理準備清單（To Do），只有當準備清單中沒有符合條件的項目時才處理待辦事項清單。優先處理最高優先級的工作，清單中的位置用於打破平局。跳過任何已完成、已封存、已受阻、等待中、已暫停或已分配給其他人的卡片 — --open --deps ready --no-assignee 會為你完成大部分過濾工作（已暫停的卡片已從 slipdock cards 的輸出中排除）— 以及任何替代卡片（↪stand-in-for:#N）：它僅標記卡片進入衝刺的位置。如果看板回答 PAUSED（JSON 中的 paused），則表示有人已暫停其上執行的 runner 工作：不要取用任何工作並停止。當你找到的卡片有子卡片時，深入其中並將這些子卡片完成，然後再回到頂層挑選下一張卡片。
• 邊做邊更新。 開始時將卡片移動到進行中狀態並分配給自己；在每個決策、意外或死胡同處記錄評論；標記它（blocked、review）並附上說明你在等待什麼的評論；當只有人才能提供你所需的東西時，建立一個等待項目並停止（slipdock wait <id> "what you need" [--on EMAIL] [--choice X]...，或使用 update_card 的 wait 參數；多個問題以 --question Q --question Q / questions 的方式傳遞，每個問題獨立，絕不作為一個區塊）：它會將卡片標記為 waiting，回答它（slipdock answer）會讓工作重新開始 — 或者，當等待的內容有日期時，改為將其暫停（slipdock snooze <id> <date> --note "…"）：它會離開清單並在指定日期回來，位於其清單的頂部；完成時，設定 completed: true 並將其移動到已完成清單。僅當史詩的彙總顯示所有子卡片都已完成時，才算完成史詩。
• 已驗證的工作，適用於看板有此功能的情況（指南中的對應行顯示 verified work: …）。在開始之前撰寫卡片的驗證標準（bar）（slipdock edit <id> --bar "…"），並且一旦工作開始，絕不嘗試更改它。使用你檢查過的內容完成它（slipdock done <id> --evidence-commit <sha> --tests a,b --suite passed:38:0 --evidence "…"）。在有第二個代理進行驗證的看板上，done 提交卡片並使其保持待處理狀態：不要自己將其移動到「已完成」。被拒絕的卡片會帶回原因（在評論中）、任務的提示以及 get_card 的 rejection（交接訊息會顯示 Rework: …）：首先閱讀該原因，因為它是下一個簡報。驗證其他人的卡片（永遠不是你自己的）意味著在一個乾淨的樹中檢出證據的提交，運行測試套件（在拉取請求看板上，檢查其 CI 在該提交時已通過），根據驗證標準進行判斷，然後執行 slipdock accept <id> 或 slipdock reject <id> --reason "…"。在一個透過拉取請求發布的看板上（看板上的行這樣說明，已聲明的任務提示和 slipdock card 也如此說明），永遠不要推送預設分支：在 card-<id> 分支上提交，推送它，建立一次拉取請求（gh pr create --head card-<id> --title "<title> (#<id>)" --fill；被拒絕的卡片的後續嘗試會推送到同一個分支），監視其檢查（完整的測試運行：在推送之前，只運行你新增或更改的測試），然後使用 slipdock done <id> --pr <url> 完成。接受卡片會合併它；不要自己合併。合併失敗會將卡片以「已拒絕」狀態返回，並附帶原因：重新設定分支基準並再次提交。
• 車道，適用於看板有啟用此功能的情況（指南中看板對應的行顯示 lanes: on）。在開始卡片之前，撰寫其工作將觸及的路徑：slipdock edit <id> --paths "lib/foo/**,docs/manual.md"，範圍應儘可能根據簡報收窄。如果因與進行中的卡片重疊而被拒絕移動，則會命名該卡片：收窄路徑，或讓該卡片保持受阻狀態；只有人可以覆蓋車道。在推送看板上，等待驗證的卡片會釋放其車道及其依賴項；在拉取請求看板上，它會同時保留兩者直到合併。無論看板是否有車道，在帶有路徑的卡片上，僅根據名稱暫存這些路徑下的檔案，如果同一個儲存庫中有其他活躍的會話，則在你自己的 git worktree 中工作（git worktree add ../<repo>-lanes/card-<id> -b card-<id>），除非 runner 已將你置於其中（$SLIPDOCK_WORKTREE）。
• 先閱讀交接記錄，中途停止時要留下一個。 卡片的交接記錄（slipdock card <id> 頂部的 Left off:；其 JSON 中的 handoff）是上一個接手的人留下的：下一步驟和簡短備註。當你接手一張卡片時，在閱讀評論之前先閱讀它。每當你未完成卡片就停止時 — 會話結束、交回、受阻、時間不夠 — 留下一個：slipdock handoff <id> --next "<the one next step>" --body "State: … Gotchas: … Open: … Pointers: …"（在 MCP 中，使用 leave_handoff）。它會取代上一個；歷史紀錄會被保留。評論是持續進行的記錄；交接記錄是當下的狀態。在一個已完成的卡片上，交接記錄是留給人的：他們必須做什麼、檢查什麼或知道什麼（例如部署、重新安裝、問題、注意事項），以 --next 表示，並用幾個要點說明情況。沒有留給他們的內容：留空，並使用 slipdock handoff <id> --clear 清除之前留下的。
• 在推送之前重新閱讀卡片，並在之後閱讀其評論。 工作檢查完畢後，再次執行 slipdock card <id>：變更的描述或比你聲稱更新的評論仍然屬於這張卡片 — 在提交之前執行此操作。在建置開始後，再次閱讀評論，看看是否有在此期間新增的內容。
• 事件和部署。 當看板記錄部署時（slipdock dora <board> 會回答而不是說傳遞指標已關閉），中斷或損壞的發布是一個標記為 incident 的普通卡片；如果你知道是哪個部署導致的，使用 slipdock incident-of <card> <deploy-id>。在修復的提交中命名該卡片（#57），如同對待任何卡片一樣：這就是其部署如何被計為修復以及卡片如何獲得其 Shipped 行的方式。絕不要手動記錄或完成部署 — 那是 CI 的工作，使用它自己的 token。
• 整理建議由人決定。 slipdock garden <board>（在 MCP 中，使用 garden）列出看板的園丁發現的內容：已完成但未關閉的史詩、卡在進行中的卡片、重複項、孤立的頁面。當被要求整理時顯示它們，並且僅套用（slipdock garden apply <id>、garden_decide）被批准的那些；在無人值守工作時，絕不套用或關閉任何一個 — 關閉操作會被記住。
• 長時間運行的工作會獲得中期更新。 如果任務需要超過一個短暫的工作時間，請在每個里程碑處記錄評論（仍在運行時） — 已完成的內容、剩下的內容、任何計劃的變更 — 並同時更新 percent_complete。在結束時一次性的總結太晚而沒有用處：一張進行中的卡片，如果上面沒有比移動操作更新的內容，會被視為已放棄。跨越多次工作階段的史詩也採用相同的處理方式，每當一個子卡片關閉時，記錄一行。
• 評論是 Markdown，並且會被快速瀏覽。 以一個粗體行開頭說明它是什麼（**Picked up.**、**Built.**、**Decision:** …），然後是簡短的項目符號，每個項目一個事實，路徑、命令和提交 ID 用反引號包裹；絕不要使用一個包含子句的密集段落。超過一行的內容使用 slipdock comment <id> --body - <<'EOF' … EOF（使用引號，以便反引號能存活）；命令列上的單字會失去其換行符。
• 提交並連結它。 當專案是一個 git 儲存庫時，一旦卡片的工作完成，請提交它 — 在關閉卡片之前 — 並在提交訊息中包含卡片 ID（#42）。關閉評論連結到該提交，或如果已開啟 PR 則連結到 PR（Commit: https://github.com/…/commit/abc1234）。如果沒有可連結的遠端，請改為提供短雜湊和分支名稱。
• 在結案報告中記錄 token 成本。 卡片上的關閉評論以一行給出工作使用的 token 數量作為結尾，例如 Token cost: ~135k tokens (context budget 15.00M → 14.86M, claim to close)。當你聲稱卡片時和再次關閉它時，記錄剩餘 token 計數器（系統訊息中的 total_tokens left）的讀數，並給出差異。如果一次連續處理多張卡片，則從每次自己的聲稱開始分別測量。如果沒有看到計數器，請說 "Token cost: not measured"，而不是估算。將相同的數字添加到史詩的進度評論中。
• 先閱讀他們的最愛。 slipdock favourites 列出此人標記的看板、列表、卡片和已儲存的檢視 — 他們實際工作的地方，這是看板列表無法告訴你的。當「我接下來應該做什麼？」被問到而沒有命名看板時，最愛是你擁有的最強提示。它們是個人化的：除非被要求，否則絕不新增或刪除。
• 已封存的看板是被擱置的工作。 slipdock boards 故意省略它們；--all 會顯示它們並帶有 archived 狀態。上面的所有內容仍然可以讀取和寫入，但未經詢問絕不從已封存的看板中挑選工作，也絕不將新工作放在那裡。
• 記錄卡片無法容納的內容。 看板說明正在做什麼；它不是存放某事物如何運作、做了什麼決定及原因、或事物的形狀的好地方。這些內容應放在看板的 Wiki 中 — slipdock page ls <board>、slipdock page read <page>、slipdock page new <board> <title...>。判斷標準是它是否會在此卡片關閉後再次被閱讀：一個決定、一個 Runbook、一個規格或一個調查結果將會被再次閱讀，並且應屬於一個頁面（透過其代碼 W-31 從卡片的關閉評論中連結起來）；進度、阻礙和現在發生的事情屬於卡片上的評論。絕不要同時做兩件事 — 重複評論的頁面是沒人信任的頁面。在開始撰寫之前先搜尋（slipdock page ls <board> --q <the thing>）：擴展現有頁面優於建立第四個關於部署的頁面。每次編輯時傳遞 --message，並對任何不是你剛剛自己撰寫的頁面的編輯傳遞 --base-hash，這樣儲存時就不會無聲地覆蓋在別人的內容之上。
• 保持標題簡短。 卡片標題最多約 60 個字元，系列標題為 <Series> <n>: <what>（例如 Agent supervision 5: Parked jobs），詳細資訊放在描述中。卡片的標題會變成一個資料夾並顯示在緊湊的清單中，如果一系列卡片共享其前 40 個字元，則在該清單中無法區分它們。
• 不要 刪除卡片（改為封存）、重寫標題以匹配你實際做的事情、整理其他人的卡片，或將卡片留在進行中狀態但沒有比移動操作更新的評論。封存或重新排序整個看板更是遠超出你的職責範圍：僅在明確要求下，並指名該看板。

適用的時機

• 「我接下來應該做什麼？」、「繼續執行計劃」、「處理待辦事項」、「下一個任務」 → 擷取指南，然後根據其規則選擇，並說明你選了哪張卡片以及原因。
• 「將此計劃放入看板」、「將其分解為任務」 → 根據指南的結構，使用帶有子卡片的史詩。
• 你已經在處理來自看板的某項任務的中途 → 卡片是記錄進度、決策和阻礙的地方，並且應在發生時記錄，而不是在最後一次性傾倒。
• 你完成了來自看板的某項任務 → 在報告完成之前，先在看板上將其關閉。