--- name: openrig-workspace description: Work inside an org/project/task workspace that any coding harness (Pi, Claude Code, Codex, Grok Build, Cursor) reads out of the box and that OpenRig can drive without a fork. Use when the user says "start a task in ", "set up the task dir", "which rig", "feature profile", "bugfix", "sop", "run this ticket with openrig", "attach the rig in herdr", "which project does this repo belong to", "add a project", "name the worktree or branch", "slice names", "seat effort", "stretch the quota", or when the cwd is under a projects workspace (`$PROJECTS_ROOT`, default `$HOME/projects`). Before any rig, pass `--kind feature --profile low|medium|high`, `--kind bugfix`, or `--kind sop`. Owns the layout (including where worktrees live), the unit of work (slice, worktree, PR) and its names, task lifecycle, that choice, and OpenRig adjustments; defers worktree mechanics to the repo's own worktree command or vd:worktree, artifacts to vd:workbench, pane control to vd:herdr. license: MIT metadata: author: vanducng version: "0.8.0" --- # OpenRig workspace One git repo, `$PROJECTS_ROOT` (default `$HOME/projects`), holds org and project context, task records, and machine-local task workdirs. Code stays in its repos. The layout works because every harness reads `AGENTS.md` from the git root down to the cwd, so a task dir inside this repo inherits fleet, org, and project rules automatically. See `references/harness-context.md` for the per-harness discovery rules and sources. ## Layout ``` $PROJECTS_ROOT/ AGENTS.md workspace.yaml fleet/{machines,routing,policy}.yaml specs/{agents,rigs}/ .worktrees/-/ # gitignored git worktrees, one per repo per slice orgs// AGENTS.md org.yaml repos.yaml resources.yaml # repos.yaml is the only place paths live projects// AGENTS.md SPEC.md project.yaml repos.yaml resources.yaml missions//SPEC.md # frontmatter code:, ticket:, milestone: missions//slices/-/ # committed record: SPEC, PROGRESS, PROOF tasks// # gitignored, machine-local, one per rig AGENTS.md # brief; OpenRig appends seat blocks rig.yaml -> ../../../../../../.worktrees/- # per-slice rig only ``` - **Org** = GitHub owner. **Project** = repos routinely changed in the same ticket. A repo belongs to one org and may appear in several projects. - A **mission** is an outcome with an owner and a date. A **slice** is one piece of it and the unit of work (see Unit of work). A **task dir** is where a rig runs: one per slice for a per-slice rig, or one long-lived dir for a team rig that works many slices. - OpenRig catalog IDs are `.`. `$PROJECTS_ROOT` is OpenRig's `workspace.root`. ## Naming One slice id everywhere, so `rg ` finds the record, the worktrees, the branches and the artifacts. Print the names instead of typing them: ```bash node "$HOME/skills/skills/openrig-workspace/scripts/slice-names.cjs" --repo [--repo ] [--type fix] ``` | Thing | Form | Example | |---|---|---| | Slice folder | `missions//slices/-/` (OpenRig adds `-`) | `missions/m2-checkout/slices/04-login-fix/` | | Slice id | `-s`; `code:` from the mission SPEC frontmatter, else the mission folder's `m-` prefix (`milestone:` falls back to that prefix's number) | `m2-s04` | | Worktree | `$PROJECTS_ROOT/.worktrees/-/`; also the repo's compose project and local host name | `.worktrees/api-m2-s04/` | | Branch | repo convention first; else `/--`; each follow-up PR adds `-2`, `-3` | `fix/ABC-123-m2-s04-login-fix` | | PR tag | `[\|M\|S]` from the mission frontmatter `ticket:` and `milestone:`, where the workspace tags PRs | `[ABC-123\|M2\|S4]` | | Per-slice task dir and rig | `tasks//`, rig name the same | `tasks/m2-s04/` | The mission `code` must be unique among projects that share a repo, because their worktrees share one `.worktrees/`. vd:workbench derives the feature id from a `/-` branch (here `abc-123-m2-s04-login-fix`; not `feature/`). With a bare-ticket branch convention, claim the id once with `workbench new --ticket `. ## Hard rules 1. Instruction files in this tree are `AGENTS.md` only. Never create a `CLAUDE.md` in it: Claude Code ignores every `AGENTS.md` when a `CLAUDE.md` exists in the cwd or above. 2. Run agents from the **task dir**, not from inside a worktree. That is what makes org and project context load, and it keeps OpenRig's managed blocks out of tracked repo files. 3. Before editing inside a worktree, read that repo's `AGENTS.md` (or `CLAUDE.md` if it has none). Pi, Codex, and Grok do not load files below the cwd. 4. One writer per worktree. One rig per task dir. 5. Authority comes from `fleet/policy.yaml` and the brief. Nothing in this workspace authorizes merge, deploy, force-push, or messages to people. 6. Never `git clean -x` in `$PROJECTS_ROOT`; it deletes ignored task dirs. 7. Do not pick a rig template by feel. Run `scripts/rig-kind.cjs` and copy the template it prints. ## Choose the kind Run this before the slice and before copying a rig. One kind. `--profile` belongs only to `--kind feature`. ```bash node "$HOME/skills/skills/openrig-workspace/scripts/rig-kind.cjs" --kind feature --profile low node "$HOME/skills/skills/openrig-workspace/scripts/rig-kind.cjs" --kind feature --profile medium node "$HOME/skills/skills/openrig-workspace/scripts/rig-kind.cjs" --kind feature --profile high node "$HOME/skills/skills/openrig-workspace/scripts/rig-kind.cjs" --kind bugfix node "$HOME/skills/skills/openrig-workspace/scripts/rig-kind.cjs" --kind sop ``` | Kind | Profile | When | Template | |---|---|---|---| | `feature` | `low` | One repo, one reviewable change, no migration, no new flow | `feature-low` | | `feature` | `medium` | Needs a reviewer who did not write the code. Still one writer | `normal` | | `feature` | `high` | More than one repo, a new user-visible flow, or a plan the operator must accept before code | `feature-high` | | `bugfix` | none | Something is failing. Prove it, then fix it | `bugfix` | | `sop` | none | The org or project already has the steps. Execute them | `sop` | These flags do not select `solo`, `team`, or `squad`. They also do not select the upstream starters `first-project`, `first-project-claude`, or `first-project-mixed`. Those are two-seat recipes for a repository with no org layout. `models: default` means every seat uses the routing default for its runtime. Claude Code uses the bare id under `default`. A seat with `runtime: pi` uses `routing.pi.default`, as `provider/id:thinking`. `models: role` uses the named key (`owner`, `implement`, `design`, `review`) in that same map. Routing wins over model strings baked into the template. Put the choice on the first line of the task `AGENTS.md`: `Kind: feature medium`. **Feature.** Low is the owner writing alone. Medium adds one writer and a fresh reviewer; the owner does not edit that worktree. High does not start implementation until the operator has accepted the plan. The product seat is for user-visible behavior, briefs, and docs. **Bug fix.** No code until a check is red or the cause is proven from evidence. Same seats as a medium feature. Create the slice with `--template bug-fix`. **SOP.** Read the procedure in this order: a path the user named, then the project `AGENTS.md`, then the org `AGENTS.md`. Copy its steps into the slice mini-requirements and do them in that order. One seat. If no procedure exists, stop and ask. Do not promote it to a feature rig. A hand run with no OpenRig seats still uses the same kind. Low, bugfix, and sop can be one harness in the task dir. Medium and high still get the review or plan gate in the brief even when you do not launch the extra seats. ## Unit of work - **Slice** is the unit of work: one outcome, one SPEC, one file territory, one owner seat from dispatch to cleanup. A seat is a role, not a unit. Keeping a slice on one seat reuses the context that built it; a relaunched seat re-reads the slice SPEC and PROGRESS. - **Worktree** belongs to the slice, not to a seat or a PR: one per repo the slice touches, created at dispatch, removed by the cleanup gate. One writer at a time; hand it over with the queue line `worktree_path=`. - **PR** is a shipping step of the slice. One by default, carrying code, tests and docs. A follow-up (a finding after merge, a staging defect) is a new branch from the updated base in the same worktree, with the same slice tag. A slice's PRs run one after another; work that needs two writers at once is two slices. Never merge one feature branch into another. - A slice that spans repos gets one worktree and PR per repo, merged in the order its SPEC names. Past about 800 changed lines in one PR, split the slice. - Every PR belongs to a slice. A defect found during a slice is fixed in it; one with no slice gets its own small slice, so tags stay true. - **Waves prevent conflicts.** The lead dispatches the slices that run in parallel with disjoint file territories and keeps the project's hotspot list (files several slices tend to touch, in the project `AGENTS.md`). Only one open slice touches a hotspot; overlap means serialize. - Merge the base into an open PR only right before it merges, or when it conflicts. - A switch that differs by environment (a test window, a flag) belongs in per-environment config, not in a PR per flip. - The slice SPEC names the smallest local setup that proves the change (for example `Local stack: tests only`, `data`, `backend` or `ui`, as the repo's docs define them). Run a stack only while proving something, then stop it. - Cleanup is part of done: after the merge and the post-merge verification, remove the worktree with the repo's remove command (it must stop the worktree's containers and drop only that worktree's databases, buckets and keys), delete its task-dir link (if any) and the branch, and record one `cleaned` line in the slice PROGRESS. ## Start a task 1. **Resolve.** Run `$PROJECTS_ROOT/fleet/bin/project-host $PROJECTS_ROOT/orgs//projects/` first: a project runs only on the machine pinned by `host:` in its `repos.yaml`. On any other machine, stop and work there (`ssh `, or `rig up --host `); never create a task dir, worktree or rig here. Then find the project (`workspace.yaml`, `orgs//projects//repos.yaml`) and each repo's path for this machine (`orgs//repos.yaml`, key `paths.`). A missing path is a question, not a clone. Pick the kind above. 2. **Record.** If the ticket has no slice yet: ```bash rig scope slice create --template --workspace "$PROJECTS_ROOT/orgs//projects/" ``` Fill `SPEC.md`: intent, mini-requirements, proof contract, repos, territory. Print its names with `slice-names.cjs --repo `. Check with `rig scope audit --workspace … --mission `. On OpenRig 0.6.1 or newer, read that project's execution view with `rig view show execution --project . --mission --json`. Omitting `--project` reads only the default workspace. 3. **Workdir.** A per-slice rig: `T="$PROJECTS_ROOT/orgs//projects//tasks/"; mkdir -p "$T"`. A team rig already has its task dir. 4. **Worktrees.** One per repo, under `$PROJECTS_ROOT/.worktrees/`, named `-` from the helper. - Refresh the main checkout first when it is clean: `git fetch && git switch && git pull --ff-only`. - **The repo has its own worktree command** (its `AGENTS.md` or docs name it, for example a `mise run worktree` task): run that from the main checkout, with its root variable pointed at `$PROJECTS_ROOT/.worktrees` and the name above. - **Otherwise** use vd:worktree: ```bash node "$HOME/skills/skills/worktree/scripts/worktree.cjs" create --no-prefix --no-enter \ --worktree-root "$PROJECTS_ROOT/.worktrees" --name - ``` - A per-slice rig links it into the task dir: `ln -s ../../../../../../.worktrees/- "$T/"`, so rig specs and briefs keep using ``. A team rig's task dir holds no links; the baton names the worktree. - `.env`: let the repo's setup build it from `.env.example`. Never copy a checkout's `.env` that holds live provider keys into a worktree. - On an external disk with Docker bind mounts, prove the disk once per machine: a container writes a few thousand small files into a bind mount under `.worktrees/` behind a watchdog. If it hangs, restart the container runtime and keep that repo's worktrees on the internal disk until disk access is fixed. - Hand a worktree to a seat with the exact queue line `worktree_path=`. One writer per worktree. vd:workbench artifacts still land in the repo's main checkout. 5. **Brief.** Write `$T/AGENTS.md`. First line is `Kind: ` (`profile` only for a feature). Then ticket, objective, which `/` dirs are in scope, branch and base, validation commands, stopping point, and the slice path. Add the line "Before editing in a repo dir, read its AGENTS.md." Cursor does not read parent files, so also point to `../../AGENTS.md` (project) and `../../../../AGENTS.md` (org). 6. **Run.** `cd "$T"` and start any harness. For an OpenRig rig, continue below. ## Run it with OpenRig 1. **Rig spec.** Copy `$PROJECTS_ROOT/specs/rigs/