Command identity and discovery
- Keep
gt2ghas the project, repository, skill, release-asset, and Homebrew formula name. Homebrew installs the executable asg2g; source builds and unrenamed release archives usegt2gh. - At the start of a task, reuse a usable command already resolved in the task
context. Otherwise, discover it once locally: try
g2g --versionfirst, thengt2gh --version. Select the first command that succeeds. If neither works, state that the user must installbrew install shhac/tap/gt2ghor provide a source/release-archivegt2ghbinary; do not assume either command exists. - Record the selected command as the task's
GT2GH_CMDand use it for every later invocation. Do not re-detect it unless it fails or the environment changes. Useg2gin Homebrew examples andgt2ghin source/archive examples.
Work in this repository
- Read
README.mdanddesign-docs/initial-scope.mdbefore changing behavior. For anything touching the gt2gh-owned branch forest, readdesign-docs/g2g-owned-graphs.mdfirst. - Treat Graphite as authoritative. Preserve the selected declared-trunk-to-leaf path in bottom-to-top order; do not manage, reorder, rebase, submit, or merge Graphite branches. A selected branch may sit in a forked tree, but siblings and descendants are not part of a v0.1 link.
linkpreviews by default. Its optional--branchtarget must work without checkout;--applyis the only path that may invokegh stack link. Bare invocation prints help.syncis preview-first and only applies when every selected-path branch already has an open GitHub PR; it must not create Graphite-only mappings or repair closed/non-open PRs.pushis a preview-first publication escape hatch. It may use Graphite's supported read-only discovery to select a path, but must never submit, restack, or otherwise mutate Graphite, and must never callgh; only--applymay run exactly onegit push --atomic --force-with-lease <remote> <branches>call. Keep the remote default explicit (origin), validate it, and never fall back to a weaker push mode. Graphite remains responsible for tracking, restacking, and submission.- By default, commands treat the selected branch as a pivot and extend through
a unique downward Graphite child chain. This remains no-checkout and excludes
siblings; reject a descendant fork rather than guessing.
--no-stackis the explicit opt-out for only the declared trunk-to-selected path. --debugis a persistent, stderr-only diagnostic flag forlink,sync, andpush. It is safe to use for local investigation but must not alter command behavior or cause agents to enable Graphite's owngt --debug.- Never guess a Graphite trunk from its name. The selected ancestry determines
the inferred trunk; multiple valid declared trunks require
--trunk, whose value must itself be declared and ancestral. - Read
design-docs/graphite-cli-contract.mdbefore changing discovery. Do not read Graphite internal metadata/configuration or usegt --debug: supported production discovery is strict, compatibility-gated noninteractive CLI parsing.
g2g-owned graphs
graph,track, anduntrackoperate on a branch forest gt2gh owns itself. They read Git only: never call Graphite or GitHub from these paths, and never make them require a network. That independence is the feature.- The model is a forest: at most one parent per branch, many children per parent, several roots. Do not reintroduce a linear assumption. Graph identity is derived from the edges, never stored; do not add graph IDs.
- Authority is per branch (
g2gorgraphite), never per graph. A whole-graph rule cannot survive two components becoming connected by an action gt2gh never observed. trackmust never choose a parent. Preview the ordered candidates and block. Recording a structure every later command trusts is not a place for a good guess.untrackmust never reparent the children it strands. Report them.- Do not record commit SHAs in the store: commits and force-pushes are content movement, not structural drift. Validate against Git at read time instead.
- gt2gh does not rebase and must not gain a checkout.
needs restackandparent missingare reported, never repaired. If restack is ever implemented, it goes in a detached temporary worktree so HEAD, the index, and the user's working tree are untouched. - The store lives under the Git common directory and is located with
git rev-parse --path-format=absolute --git-common-dir. The bare form is relative to the working directory and silently wrong from a subdirectory. Writes are temp-file plus rename.storeSchemaVersionis separate from the--jsonschemaVersion; an unrecognised store version fails closed. --scope branch|path|subtree|graphis graph selection, not projection policy. Displaying a subtree does not imply a subtree can be linked on GitHub.--no-stackon the Graphite-backed commands is the same axis as--scope branch; unifying them is a deliberate, separate change.
Develop and test
- Keep external process calls behind
internal/subprocess.Runner. Tests must use fakegtandghexecutables onPATH, including captured supported Graphite text fixtures; never require credentials, network access, or real CLI installations. Graph ancestry is the one exception where a PATH fake proves nothing — it answers whatever it is asked, and the question is what Git considers reachable — so those cases build a throwaway local repository with synthetic branch names and no remote. - Preserve the
completion bash|zsh|fishinterface. Dynamic--branchand--trunkcompletion must remain deterministic, read-only, and checkout-free. - Run
gofmt -won changed Go files andgo test ./.... Usego vet ./...when changing Go code or preparing a release. - Use
git hunkfor any staging. Do not commit, tag, push, or invoke realgt/ghmutations unless the user explicitly asks.
Use safely
- For a person who wants an editor workflow,
g2g submit --editopens one temporary JSON document, not a buffer per PR. It retains the document on all failures and after preview; successful--edit --applycleans it up unless--keep-specis present.
Submitting pull requests
-
submitis a preview-first PR creation recovery path. It must never invokegt submit, restack Graphite, or retarget an existing PR. Its--applyboundary validates/revalidates first, atomically pushes refs, creates only missing draft PRs, then links the eligible stack. -
For non-interactive use, create a private temporary directory with
g2g submit --write-spec <dir>, completesubmission.json, validate withg2g submit --spec <dir>/submission.json, then add--apply. Keep the spec on failure and state exact repair/validation/retry commands. Multiple PR templates require--template <name>or--no-template; never guess. -
Prefer
--json(or--porcelain) over parsing the human preview. Both are renderers over the same validated view, they suppress colour and every human-facing line, andschemaVersionsignals breaking changes. Never scrape the pretty graph. -
A blocked preview names the repairing command: merged pull requests point at
gt sync(Graphite owns restacking; no gt2gh command helps), missing or closed ones atg2g submit, a wrong base atg2g sync. Two open pull requests for one branch is deliberately unadvised — a person must choose. -
statusis the read-only triage entry point. It renders one selected Graphite path and reports each selected PR's native GitHub stack membership from the same batched PR query; keep the healthy case to one compact summary line and annotate only missing/conflicting nodes.unlinkis the deliberate inverse oflink: it discovers the GitHub stack number from the selected path and refuses rather than guesses when that path is unlinked or spans several stacks, accepts--stack-numberto override, previews first, and only--applyinvokesgh stack unstack. It must never alter Graphite, branches, PR content, reviewers, or PR lifecycle. -
After command discovery, use the resolved command's
--helporlink --helpto inspect the current interface (for example,g2g link --helpafter a Homebrew install). -
Require read-only discovery and dry-run output before
sync --applycan change GitHub state.