|
| 1 | +# Rig Add Shorthand And .gt/rig.toml |
| 2 | + |
| 3 | +This document defines a shorthand for adding rigs to a town, along with a |
| 4 | +repository manifest (`.gt/rig.toml`) that standardizes crew defaults, naming, |
| 5 | +remotes, and setup/update behavior across towns. |
| 6 | + |
| 7 | +## Goals |
| 8 | + |
| 9 | +- Provide a one-liner to install a rig plus a crew workspace. |
| 10 | +- Reuse rig conventions (crew/polecat settings, beads prefix, upstreams). |
| 11 | +- Capture upstream vs origin (fork vs owner) and configure remotes correctly. |
| 12 | +- Offer a reliable rig-level setup/update behavior (self-update). |
| 13 | +- Keep current PR submission behavior unchanged by default. |
| 14 | + |
| 15 | +## Non-Goals |
| 16 | + |
| 17 | +- Replace `gt rig add` or `gt rig quick-add` (they remain supported). |
| 18 | +- Change default PR submission workflows. |
| 19 | +- Require forks for non-owners (prompt, don't enforce). |
| 20 | + |
| 21 | +## Terminology |
| 22 | + |
| 23 | +- **Upstream**: Canonical repo (e.g., `steveyegge/gastown`). |
| 24 | +- **Origin**: User's writable fork or local remote. |
| 25 | +- **Manifest**: `.gt/rig.toml` file in the repo. |
| 26 | + |
| 27 | +## CLI Overview |
| 28 | + |
| 29 | +### `gt rig add` |
| 30 | + |
| 31 | +Adds a rig and applies manifest defaults when `.gt/rig.toml` is present (unless `--ignore-manifest`). |
| 32 | + |
| 33 | +Examples: |
| 34 | + |
| 35 | +```bash |
| 36 | +gt rig add gastown https://github.com/steveyegge/gastown.git --crew $USER |
| 37 | +gt rig add beads https://github.com/steveyegge/beads.git --crew $USER |
| 38 | +gt rig add myproject https://github.com/acme/myproject.git --crew alice |
| 39 | +gt rig add https://github.com/acme/myproject.git --crew alice |
| 40 | +gt rig add . --crew alice # local repo (quick-add) |
| 41 | +``` |
| 42 | + |
| 43 | +Core flags: |
| 44 | + |
| 45 | +- `--crew <name>`: Create ONLY these crew workspaces (overrides manifest crew list). |
| 46 | +- `--no-crew`: Skip crew creation entirely. |
| 47 | +- `--start`: Autostart all created crew sessions. |
| 48 | +- `--ignore-manifest`: Ignore `.gt/rig.toml` entirely (no defaults, no setup, no crew list). |
| 49 | +- `--yes`: Non-interactive (accept defaults, skip prompts). |
| 50 | +- `--prefix <p>`: Override beads prefix. |
| 51 | +- `--branch <name>`: Override default branch. |
| 52 | +- `--local-repo <path>`: Use local reference repo for cloning. |
| 53 | +- `--upstream <url>`: Explicitly set upstream remote. |
| 54 | +- `--origin <url>`: Explicitly set origin remote. |
| 55 | +- `--fork <prompt|require|never>`: Fork handling policy (default: `prompt`). |
| 56 | + |
| 57 | +`gt rig quick-add` should delegate to `gt rig add .` so it gains |
| 58 | +the same manifest and fork logic. |
| 59 | + |
| 60 | +### `gt rig update` |
| 61 | + |
| 62 | +Check or update a rig against upstream/origin. |
| 63 | + |
| 64 | +Examples: |
| 65 | + |
| 66 | +```bash |
| 67 | +gt rig update gastown --check |
| 68 | +gt rig update gastown --pull |
| 69 | +gt rig update gastown --pull --ignore-manifest |
| 70 | +``` |
| 71 | + |
| 72 | +Behavior: |
| 73 | +- `--check`: fetch and report ahead/behind vs configured default branch. |
| 74 | +- `--pull`: update mayor/refinery clones (no crew updates by default). |
| 75 | +- `--pull` runs manifest setup by default; use `--ignore-manifest` to skip. |
| 76 | +- If neither flag is provided, default to `--check`. |
| 77 | + |
| 78 | +## Presets |
| 79 | + |
| 80 | +Built-in presets for common rigs: |
| 81 | + |
| 82 | +| Preset | Upstream | Default Setup Command | |
| 83 | +|--------|----------|-------------------------| |
| 84 | +| gastown | `https://github.com/steveyegge/gastown.git` | `go install ./cmd/gt` | |
| 85 | +| beads | `https://github.com/steveyegge/beads.git` | `go install ./cmd/bd` | |
| 86 | + |
| 87 | +Presets are shorthand for a manifest (see below) and still honor CLI overrides. |
| 88 | + |
| 89 | +## Manifest: `.gt/rig.toml` |
| 90 | + |
| 91 | +The manifest is optional. If present, it provides rig defaults and the setup |
| 92 | +command. TOML aligns with existing usage (formulas and recipes). |
| 93 | + |
| 94 | +Example: |
| 95 | + |
| 96 | +```toml |
| 97 | +version = 1 |
| 98 | + |
| 99 | +[rig] |
| 100 | +name = "gastown" |
| 101 | +prefix = "gt" |
| 102 | +default_branch = "main" |
| 103 | + |
| 104 | +[git] |
| 105 | +upstream = "https://github.com/steveyegge/gastown.git" |
| 106 | +fork_policy = "prompt" # prompt|require|never |
| 107 | + |
| 108 | +[setup] |
| 109 | +command = "go install ./cmd/gt" |
| 110 | +workdir = "." |
| 111 | + |
| 112 | +[settings] |
| 113 | +path = ".gt/rig-settings.json" |
| 114 | + |
| 115 | +[[crew]] |
| 116 | +name = "max" |
| 117 | +agent = "codex" |
| 118 | +model = "gpt-5" |
| 119 | +account = "work" |
| 120 | +branch = true |
| 121 | + |
| 122 | +[[crew]] |
| 123 | +name = "alex" |
| 124 | +agent = "claude" |
| 125 | +account = "personal" |
| 126 | +``` |
| 127 | + |
| 128 | +### Field Semantics |
| 129 | + |
| 130 | +- `rig.name`: default rig name (sanitized if needed). |
| 131 | +- `rig.prefix`: default beads prefix, used only when no tracked `.beads/` exists. |
| 132 | +- `rig.default_branch`: fallback if remote default can't be detected. |
| 133 | +- `git.upstream`: canonical repo URL (used for update checks). |
| 134 | +- `git.fork_policy`: how to prompt for fork (`prompt` default). |
| 135 | +- `setup.command`: command run after `gt rig add` or `gt rig update --pull` unless `--ignore-manifest`. |
| 136 | +- `setup.workdir`: relative path inside repo (default: repo root). |
| 137 | +- `settings.path`: optional JSON file copied into `<rig>/settings/config.json`. |
| 138 | +- `crew`: list of crew entries (created but not started). |
| 139 | + |
| 140 | +Crew entry fields: |
| 141 | + |
| 142 | +- `crew.name` (required): crew workspace name. |
| 143 | +- `crew.agent` (optional): agent alias or built-in preset (e.g., `codex`, `claude`). |
| 144 | +- `crew.model` (optional): model name for the agent (appended to args when supported). |
| 145 | +- `crew.account` (optional): account handle for the agent runtime. |
| 146 | +- `crew.branch` (optional): `true` to create `crew/<name>` branch or a string to set an explicit branch. |
| 147 | +- `crew.args` (optional): extra CLI args appended when starting the crew session. |
| 148 | +- `crew.env` (optional): environment variables to set when starting the session. |
| 149 | + |
| 150 | +### Crew Behavior |
| 151 | + |
| 152 | +- If the manifest includes `[[crew]]` entries, those crew are created (not started). |
| 153 | +- If `--crew` is provided, only those crew are created. If a provided name |
| 154 | + matches a manifest entry, its config is used; otherwise defaults apply. |
| 155 | +- `--no-crew` disables crew creation entirely. |
| 156 | +- `--start` autostarts all crew created by the command. |
| 157 | +- Model support is determined by the agent preset in `settings/agents.json`. |
| 158 | + If `supports_model` is true, append `model_flag` (or `--model` if unset). |
| 159 | +- If `crew.model` is set but the agent does not support models, warn and skip it |
| 160 | + (users can still pass custom flags via `crew.args`). |
| 161 | + |
| 162 | +## Fork Workflow |
| 163 | + |
| 164 | +When upstream is `steveyegge/gastown` or `steveyegge/beads` and the GitHub |
| 165 | +user is not `steveyegge`, `gt rig add` should: |
| 166 | + |
| 167 | +1. Detect if a fork exists (`gh repo view <user>/<repo>`). |
| 168 | +2. Prompt to use existing fork, create a fork, or continue read-only. |
| 169 | +3. Configure remotes: |
| 170 | + - `upstream` = canonical repo |
| 171 | + - `origin` = user fork (or upstream if owner) |
| 172 | + |
| 173 | +If forked, configure beads sync to pull from upstream: |
| 174 | + |
| 175 | +```bash |
| 176 | +bd config set sync.remote upstream |
| 177 | +``` |
| 178 | + |
| 179 | +## Data Model Changes |
| 180 | + |
| 181 | +Extend rig metadata so update/fork info persists: |
| 182 | + |
| 183 | +- `<rig>/config.json`: store `git.upstream`, `git.origin`, `setup.command`. |
| 184 | +- `mayor/rigs.json`: store upstream/origin for routing and future `gt crew add`. |
| 185 | +- `crew/<name>/state.json`: store default crew start config (agent, model, account, args, env). |
| 186 | +- `settings/agents.json`: add optional `model_flag` and `supports_model` for agent presets. |
| 187 | + |
| 188 | +Back-compat: if these fields are missing, assume `origin` only. |
| 189 | + |
| 190 | +## Error Handling |
| 191 | + |
| 192 | +- If `gh` is missing, fork prompting should fall back to a read-only flow. |
| 193 | +- If the manifest is missing or invalid, proceed with defaults and warn. |
| 194 | +- If `setup.command` fails, print the command and exit non-zero. |
| 195 | + |
| 196 | +## Testing |
| 197 | + |
| 198 | +- Integration test: `gt rig add` with a local repo containing `.gt/rig.toml`. |
| 199 | +- Integration test: fork flow using a local "upstream + fork" repo pair. |
| 200 | +- Verify remotes, settings copy, crew creation, and update check output. |
| 201 | + |
| 202 | +## Compatibility Notes |
| 203 | + |
| 204 | +- `gt rig add` remains the primary command; manifest handling is additive. |
| 205 | +- `gt rig quick-add` becomes a thin wrapper over `gt rig add`. |
| 206 | +- PR submission defaults remain unchanged; optional `gt rig submit` can be added later. |
0 commit comments