GOBB / 使用指南

让 Gobb 接续每一项任务。

实用说明 repository-owned 脉络、团队审阅、安全 Hub 访问和可观察交接。

使用两个分开的目录

CLI_SOURCE_DIR 是 organizer-approved Gobb source checkout 的绝对路径；只在此执行 build、version 和 install 命令。

WORK_REPOSITORY 是你现有、由 organizer 协助准备并已初始化 Gobb 的 repository 绝对路径；只在此执行 context 和 working-repository 命令。

1. 用 repository 脉络接续个人工作

从现有工作目录开始。可持久接续下一位人员或 AI 任务的是 repository，而不是聊天记录。

使用已为 Gobb 初始化的 repository。每项任务开始时，先查看返回的 required context，再修改文件。
当前 CLI 只支持从 organizer-approved checkout source build，并需要 Go 1.26+、Git 和 make；没有可替代的已核实 semantic release、prebuilt download、checksum 或 package-manager install。
在工作附近保留已接受决定、重要发现、限制及支持证据；不要把推测或未解问题写成指引。
交接前执行 finish 检查，处理可采取行动的发现，并记下下一步。
新的 AI 任务先读 repository-owned 脉络。历史只解释工作如何走到现在，不会成为比 repository 已接受指引更新的权威。

完整示例：一个已准备 repository、两项 AI 任务

在本地 shell 将 CLI_SOURCE_DIR 和 WORK_REPOSITORY 设成各自真实绝对路径；不可指向同一个 checkout。
在 CLI_SOURCE_DIR build 或验证 CLI；然后在 WORK_REPOSITORY 开始第一项任务，修改前先阅读 required_context 返回的每一条路径。
执行工作。具体示例：修改已 tracked 的 sample path docs/sample-handoff.md，或换成 repository 的实际 tracked file；先用 git diff 查看该路径，再检查 git status。
按 repository 现有 workflow，将一项已接受 decision、重要 finding 和 supporting evidence 记录到现有 owner；没有通用 write command。
在 WORK_REPOSITORY 执行 finish，处理可采取行动的 finding，并列出下一步。
在新的 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。

2. 通过 Hub 推进团队脉络

经安全邀请加入并登录，再选择 organizer 提供的 organization 和 Project。

动手前先读 accepted context。Accepted context 是当前团队事实；proposal 是候选变更；release 是另行发布的版本。
浏览器没有 authoring 操作时，在真实 Git checkout 使用 CLI 和 Git authoring；不要把虚构 Hub demo 当成 live service。
审阅精确 target、diff、理由和证据。Approve 记录审阅决定；accept 才更新 accepted context，两者不会暗中代替对方。
交给同事时，列出 Project、已接受结果、未解 proposal 或 operation、证据，以及一个可观察的下一步。

具体团队 authoring 和 review 示例

WORK_REPOSITORY 使用真实、独立且干净的 Git worktree。修改已 tracked 的 sample path docs/sample-handoff.md，或换成实际 tracked target。
执行所示 git diff 和 git status，核对精确 target，排除无关变更。
由 organizer 或现有已核实 submission flow 提交 proposal。本流程没有已核实的 proposal-submission CLI，因此本页不提供假命令。
在 Hub 审阅精确 target、diff、理由和 evidence；记录 approve；再以独立操作执行 accept。
确认所产生 operation 或 receipt 的 terminal state，再将 Project、已接受结果、剩余工作和一个可观察下一步交给同事。

命令

cd "$WORK_REPOSITORY"
git diff -- docs/sample-handoff.md
git status --short

3. 检查访问并绑定合资格 checkout

Organizer 通过安全渠道提供 HUB_ORIGIN、ORG_ID、PROJECT_ID 和短效 GOBB_HUB_TOKEN。在本页以外的本地环境设置 token；绝不可贴进 AI、聊天、截图或文档。

将大写 metavariable 换成 organizer 提供的值；它们是标签，不是要照字输入的 shell 内容。
变更 workspace 前先读当前 Project access。
只绑定现有且合资格的本地 checkout。Bind 只记录关联，不会 clone 内容。
资格要求：已初始化 primary repository、configured path 上 ignored 或 untracked 的 context checkout、独立且干净的 Git worktree、完全相符的 origin clone URL、transport-ready Project，而且没有 tracked context/current 或 context/working/synced。
绑定后刷新状态。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。

4. 按可观察边界排查

保留失败命令或页面、精确状态和 request ID。不要把不确定结果猜成成功。

找不到 binary 或 command：在已批准 source checkout 执行 ./bin/gobb version，或确认 make install-local 显示的目的地已加入 PATH。
Origin 或 ID 无效：向 organizer 重新核对 HUB_ORIGIN、ORG_ID 和 PROJECT_ID，不要猜值。
Token 丢失或过期：经安全渠道要求新的短效 token；不要复制到 ticket 或聊天。
未验证、禁止或 Project unavailable：交给 organizer 用 request ID 和当前 membership/grant state 区分 identity、access 与 availability。
Transport unavailable：Project 可存在而 Git transport 尚未 ready；等待权威 transport-ready state，不要虚构 clone URL。
Already bound、drifted 或 workspace missing：先刷新 status，按精确报告修正 checkout state，再重试 bind。
Context stale：重新加载当前 required context；历史仍是证据，不是更新权威。
Proposal conflict：再次审阅当前 target 和 diff 才作下一次 review；保留 request ID，不要推断已接受。