gobb
GOBB / 使用指南

讓 Gobb 接續每一項任務。

實用說明 repository-owned 脈絡、團隊審閱、安全 Hub 存取與可觀察交接。

使用兩個分開的目錄

CLI_SOURCE_DIR 是 organizer-approved Gobb source checkout 的絕對路徑；只在此執行 build、version 與 install 命令。

WORK_REPOSITORY 是你既有、由 organizer 協助準備並已初始化 Gobb 的 repository 絕對路徑；只在此執行 context 與 working-repository 命令。

01

1. 用 repository 脈絡接續個人工作

從既有工作目錄開始。可持久接續下一位人員或 AI 任務的是 repository，而不是聊天記錄。

  1. 使用已為 Gobb 初始化的 repository。每項任務開始時，先檢視回傳的 required context，再修改檔案。

  2. 目前 CLI 只支援從 organizer-approved checkout source build，並需要 Go 1.26+、Git 與 make；沒有可取代的已核實 semantic release、prebuilt download、checksum 或 package-manager install。

  3. 在工作附近保留已接受決定、重要發現、限制及支持證據；不要把推測或未解問題寫成指引。

  4. 交接前執行 finish 檢查，處理可採取行動的發現，並記下下一步。

  5. 新的 AI 任務先讀 repository-owned 脈絡。歷史只解釋工作如何走到現在，不會成為比 repository 已接受指引更新的權威。

完整例子：一個已準備 repository、兩項 AI 任務

  1. 在本機 shell 把 CLI_SOURCE_DIR 與 WORK_REPOSITORY 設成各自真實絕對路徑；不可指向同一個 checkout。
  2. 在 CLI_SOURCE_DIR build 或驗證 CLI；然後在 WORK_REPOSITORY 開始第一項任務，修改前先閱讀 required_context 回傳的每一條路徑。
  3. 執行工作。具體例子：修改已 tracked 的 sample path docs/sample-handoff.md，或換成 repository 的實際 tracked file；先以 git diff 檢視該路徑，再檢查 git status。
  4. 依 repository 既有 workflow，把一項已接受 decision、重要 finding 與 supporting evidence 記進既有 owner；沒有通用 write command。
  5. 在 WORK_REPOSITORY 執行 finish，處理可採取行動的 finding，並列出下一步。
  6. 在新的 AI 任務再次執行 start，先讀目前 repository context。Git/history 只作工作如何走到這裡的 evidence，絕不是比已接受 repository instructions 更新的 authority。
命令
cd "$WORK_REPOSITORY"
git diff -- docs/sample-handoff.md
git status --short

從批准的 checkout build CLI。

命令
cd "$CLI_SOURCE_DIR"
make build

可觀察結果: Build 完成並產生 bin/gobb。

驗證 source-built CLI。

命令
cd "$CLI_SOURCE_DIR"
./bin/gobb version

可觀察結果: CLI 顯示版本。

可選：本機安裝並驗證 PATH。

命令
cd "$CLI_SOURCE_DIR"
make install-local
export PATH="$HOME/.local/bin:$PATH"
gobb version

可觀察結果: make install-local 會把 binary 安裝到 $HOME/.local/bin/gobb；執行所示 PATH export 後，gobb version 會解析到該 binary。

載入目前 repository 脈絡。

命令
cd "$WORK_REPOSITORY"
gobb agent-context --if-managed --phase start --json

可觀察結果: JSON 會列出 required context 與任何阻擋工作的 guard finding。

離開任務前檢查交接。

命令
cd "$WORK_REPOSITORY"
gobb agent-context --if-managed --phase finish --json

可觀察結果: 結果會列出尚未處理的文件、working state、guard 或 completion finding。

02

2. 透過 Hub 推進團隊脈絡

經安全邀請加入並登入，再選擇 organizer 提供的 organization 與 Project。

  1. 動手前先讀 accepted context。Accepted context 是目前團隊事實；proposal 是候選變更；release 是另行發布的版本。

  2. 瀏覽器沒有 authoring 動作時，在真實 Git checkout 使用 CLI 與 Git authoring；不要把虛構 Hub demo 當成 live service。

  3. 審閱精確 target、diff、理由及證據。Approve 記錄審閱決定；accept 才更新 accepted context，兩者不會暗中代替對方。

  4. 交給同事時，列出 Project、已接受結果、未解 proposal 或 operation、證據，以及一個可觀察的下一步。

具體團隊 authoring 與 review 例子

  1. WORK_REPOSITORY 使用真實、獨立且乾淨的 Git worktree。修改已 tracked 的 sample path docs/sample-handoff.md，或換成實際 tracked target。
  2. 執行所示 git diff 與 git status，核對精確 target，排除無關變更。
  3. 由 organizer 或既有已核實 submission flow 提交 proposal。本流程沒有已核實的 proposal-submission CLI，因此本頁不提供假命令。
  4. 在 Hub 審閱精確 target、diff、理由與 evidence；記錄 approve；再以獨立動作執行 accept。
  5. 確認所產生 operation 或 receipt 的 terminal state，再把 Project、已接受結果、剩餘工作與一個可觀察下一步交給同事。
命令
cd "$WORK_REPOSITORY"
git diff -- docs/sample-handoff.md
git status --short
03

3. 檢查存取並綁定合資格 checkout

Organizer 透過安全渠道提供 HUB_ORIGIN、ORG_ID、PROJECT_ID 及短效 GOBB_HUB_TOKEN。在本頁以外的本機環境設定 token；絕不可貼進 AI、聊天、截圖或文件。

  1. 把大寫 metavariable 換成 organizer 提供的值；它們是標籤，不是要照字輸入的 shell 內容。

  2. 變更 workspace 前先讀目前 Project access。

  3. 只綁定既有且合資格的本機 checkout。Bind 只記錄關聯，不會 clone 內容。

  4. 資格要求：已初始化 primary repository、configured path 上 ignored 或 untracked 的 context checkout、獨立且乾淨的 Git worktree、完全相符的 origin clone URL、transport-ready Project，而且沒有 tracked context/current 或 context/working/synced。

  5. 綁定後刷新狀態。gobb hub pair 是受 guard 保護的 acceptance-record workflow，不是 onboarding。

讀取目前 Project access。

命令
cd "$WORK_REPOSITORY"
gobb hub project --hub-origin HUB_ORIGIN --organization ORG_ID --project PROJECT_ID

可觀察結果: 命令會回報目前 Project capability 或可採取行動的 access failure。

綁定已合資格的 checkout。

命令
cd "$WORK_REPOSITORY"
gobb hub workspace bind --hub-origin HUB_ORIGIN --organization ORG_ID --project PROJECT_ID

可觀察結果: Workspace 記錄精確 Hub organization/Project 關聯，不會 clone。

重新檢查 live access 與 workspace state。

命令
cd "$WORK_REPOSITORY"
gobb hub workspace status --refresh

可觀察結果: 刷新結果會顯示 unavailable access、transport、drift 或 binding state。

04

4. 依可觀察界線排查

保留失敗命令或頁面、精確狀態及 request ID。不要把不確定結果猜成成功。

  1. 找不到 binary 或 command：在已批准 source checkout 執行 ./bin/gobb version，或確認 make install-local 顯示的目的地已加入 PATH。

  2. Origin 或 ID 無效：向 organizer 重核 HUB_ORIGIN、ORG_ID 與 PROJECT_ID，不要猜值。

  3. Token 遺失或過期：經安全渠道要求新的短效 token；不要複製到 ticket 或聊天。

  4. 未驗證、禁止或 Project unavailable：交給 organizer 以 request ID 及目前 membership/grant state 分辨 identity、access 與 availability。

  5. Transport unavailable：Project 可存在而 Git transport 尚未 ready；等待權威 transport-ready state，不要虛構 clone URL。

  6. Already bound、drifted 或 workspace missing：先刷新 status，按精確回報修正 checkout state，再重試 bind。

  7. Context stale：重新載入目前 required context；歷史仍是證據，不是更新權威。

  8. Proposal conflict：再次審閱目前 target 與 diff 才作下一次 review；保留 request ID，不要推斷已接受。