A practical guide to repository-owned context, team review, secure Hub access, and an observable handoff.
Use two separate directories
CLI_SOURCE_DIR is the absolute path of the organizer-approved Gobb source checkout. Run only build, version, and install commands there.
WORK_REPOSITORY is the absolute path of your existing, organizer-assisted prepared and already initialized Gobb repository. Run context and working-repository commands there.
01
1. Continue personal work with repository context
Start in an existing work directory. The repository—not chat history—is the durable source for the next person or AI task.
Use a repository that is already initialized for Gobb. At the start of a task, inspect the returned required context before changing files.
Current CLI installation is source-build only from an organizer-approved checkout and requires Go 1.26+, Git, and make. There is no verified semantic release, prebuilt download, checksum, or package-manager install to substitute.
Keep accepted decisions, material findings, constraints, and the evidence that supports them near the work. Do not turn guesses or open questions into instructions.
Before handoff, run the finish check, resolve actionable findings, and record the next action.
In a new AI task, read repository-owned context first. Use history to explain how the work arrived here, never as authority newer than accepted repository instructions.
Worked journey: one prepared repository, two AI tasks
Set CLI_SOURCE_DIR and WORK_REPOSITORY in your local shell to their real absolute paths; do not point them at the same checkout.
Build or verify the CLI in CLI_SOURCE_DIR. Then start the first task in WORK_REPOSITORY and read every path returned in required_context before editing.
Do the work. For a concrete example, edit the already tracked sample path docs/sample-handoff.md, or substitute the actual tracked file in your repository; inspect only that path with git diff, then check git status.
Record one accepted decision, material finding, and supporting evidence in the repository’s existing owner according to its workflow. There is no universal write command.
Run finish in WORK_REPOSITORY, resolve actionable findings, and name the next action.
In a new AI task, run start again and read current repository context first. Consult Git/history as evidence of how the work arrived here, never as authority newer than accepted repository instructions.
Command
cd "$WORK_REPOSITORY"
git diff -- docs/sample-handoff.md
git status --short
Build the CLI from the approved checkout.
Command
cd "$CLI_SOURCE_DIR"
make build
Observable result: The build completes and produces bin/gobb.
Verify the source-built CLI.
Command
cd "$CLI_SOURCE_DIR"
./bin/gobb version
Observable result: The CLI prints its version.
Optionally install locally, then verify PATH.
Command
cd "$CLI_SOURCE_DIR"
make install-local
export PATH="$HOME/.local/bin:$PATH"
gobb version
Observable result: make install-local places the binary at $HOME/.local/bin/gobb; after the shown PATH export, gobb version resolves to it.
Load the current repository context.
Command
cd "$WORK_REPOSITORY"
gobb agent-context --if-managed --phase start --json
Observable result: The JSON identifies required context and any blocking guard findings.
Check the handoff before leaving the task.
Command
cd "$WORK_REPOSITORY"
gobb agent-context --if-managed --phase finish --json
Observable result: The result names unresolved documentation, working-state, guard, or completion findings.
02
2. Move team context through Hub
Join through a secure invitation, sign in, then choose the organizer-provided organization and Project.
Read accepted context before authoring. Accepted context is current team truth; a proposal is a candidate change; a release is a separately published version.
Author in the real Git checkout with the CLI and Git where the browser has no authoring action. Do not treat the fictional Hub demo as a live service.
Review the exact target, diff, reasoning, and evidence. Approval records a review decision; acceptance updates accepted context. One does not silently perform the other.
For a colleague handoff, name the Project, accepted result, unresolved proposal or operation, evidence, and one observable next action.
Concrete team authoring and review example
Use a real, separate, clean Git worktree for WORK_REPOSITORY. Edit the already tracked sample path docs/sample-handoff.md, or replace it with the actual tracked target.
Run the shown git diff and git status commands; verify the exact target and keep unrelated changes out.
Have the organizer or an existing verified submission flow submit the proposal. No proposal-submission CLI is documented here because none is verified for this journey.
In Hub, review the exact target, diff, reasoning, and evidence; record approval; then perform acceptance as a separate action.
Confirm the resulting terminal operation or receipt, then hand the colleague the Project, accepted result, remaining work, and one observable next action.
Command
cd "$WORK_REPOSITORY"
git diff -- docs/sample-handoff.md
git status --short
03
3. Check access and bind an eligible checkout
Receive HUB_ORIGIN, ORG_ID, PROJECT_ID, and a short-lived GOBB_HUB_TOKEN from the organizer through a secure channel. Set the token in your local environment outside this page; never paste it into AI, chat, screenshots, or documentation.
Replace the uppercase metavariables with values supplied by the organizer. They are labels, not literal shell input.
Read current Project access before changing a workspace.
Bind only an existing eligible local checkout. Binding records the association; it does not clone content.
Eligibility requires an initialized primary repository, an ignored or untracked context checkout at the configured path, a separate clean Git worktree, the exact origin clone URL, a transport-ready Project, and no tracked context/current or context/working/synced.
Refresh status after binding. gobb hub pair is a guarded acceptance-record workflow, not onboarding.
Observable result: The workspace records the exact Hub organization and Project association; no clone is performed.
Recheck live access and workspace state.
Command
cd "$WORK_REPOSITORY"
gobb hub workspace status --refresh
Observable result: The refreshed status exposes unavailable access, transport, drift, or binding state.
04
4. Troubleshoot by the observed boundary
Keep the failing command or page, its exact state, and any request ID. Do not replace an uncertain result with a success guess.
Binary missing or command not found: run ./bin/gobb version from the approved source checkout, or verify that the make install-local destination is on PATH.
Invalid origin or identifiers: recheck HUB_ORIGIN, ORG_ID, and PROJECT_ID with the organizer; do not guess values.
Missing or expired token: request a new short-lived token through the secure channel; do not copy one into a ticket or chat.
Unauthenticated, forbidden, or unavailable Project: use the request ID and current membership/grant state to let the organizer distinguish identity, access, and availability.
Transport unavailable: the Project can exist while Git transport is not ready; wait for an authoritative transport-ready state rather than inventing a clone URL.
Already bound, drifted, or missing workspace: run refreshed status and correct the exact reported checkout state before retrying bind.
Stale context: reload current required context; history remains evidence, not newer authority.
Proposal conflict: return to the current target and diff before another review. Preserve the request ID and do not infer acceptance.