From 3b6a5c67373c1b6760900ab695a7bf39299b4113 Mon Sep 17 00:00:00 2001 From: Viktor Barzin Date: Wed, 10 Jun 2026 17:49:43 +0000 Subject: [PATCH] workstation: worktree-first feature work for all agents [ci skip] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Viktor asked that every feature task be developed in its own git worktree and merged into master when done, enabling multiple agents to work the same project concurrently. Encode the org rule in the managed claudeMd (self-deploys to /etc via the hourly reconcile), add the worktree-first paragraph to the AGENTS.md non-admin landing recipe, and gitignore .worktrees/ so per-feature worktrees can live at the repo root. Full lifecycle: ~/.claude/rules/execution.md §3. Co-Authored-By: Claude Fable 5 --- .gitignore | 3 +++ AGENTS.md | 10 ++++++++++ scripts/workstation/managed-settings.json | 2 +- 3 files changed, 14 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 3475f32a..0ad4a53e 100755 --- a/.gitignore +++ b/.gitignore @@ -103,3 +103,6 @@ stacks/terminal/clipboard-upload/clipboard-upload # Plaintext terraform state — NEVER commit (use SOPS-encrypted .tfstate.enc only) terraform.tfstate terraform.tfstate.backup + +# Per-feature git worktrees (worktree-first workflow — execution.md §3) +.worktrees/ diff --git a/AGENTS.md b/AGENTS.md index 7559d276..054a6ded 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -240,6 +240,16 @@ push straight to `master` — no PR gate — and the record of *what changed and why* is what matters. Force-push is disabled for everyone, so master history is append-only. +**Feature-sized work is worktree-first** (org rule, 2026-06-10): develop in an +isolated worktree (`.worktrees/`, branch `/` off +`forgejo/master`) so concurrent agent sessions never collide in the clone, then +land by merging latest master into the branch and pushing it +(`git push forgejo HEAD:master`, or the PR fallback below if not whitelisted) — +the audit-trail rules below apply to the branch's commit messages all the same. +Locked (git-crypt) clones can use plain `git worktree add`. Trivial +single-commit fixes may be committed directly on a clean `master`. Full +lifecycle: `~/.claude/rules/execution.md` §3. + To land a finished change from such a clone: 1. Commit on `master`. **The commit message is the audit trail** — this matters diff --git a/scripts/workstation/managed-settings.json b/scripts/workstation/managed-settings.json index d9a7ccaf..fd2d2a3b 100644 --- a/scripts/workstation/managed-settings.json +++ b/scripts/workstation/managed-settings.json @@ -1,4 +1,4 @@ { - "claudeMd": "# Viktor Barzin homelab — shared multi-user Claude Code Workstation (devvm)\n\nYou are running as a specific OS user on a SHARED devvm Workstation, not as the admin. These org-wide rules apply to EVERY user and sit at the top of settings precedence (they cannot be overridden by a user's own config):\n\n- Respect your permission tier. Your kubectl, Vault, and infra access are scoped to your RBAC tier (admin / power-user / namespace-owner). Do not attempt to escalate privileges or reach another user's resources.\n- Secrets are per-user. Never read another user's home directory, credentials, tokens, or ~/.claude secrets. Your own secrets live in your home at mode 600.\n- Infrastructure changes go through Terraform/Terragrunt — never direct kubectl apply/edit/patch. Committed stack changes are auto-applied by CI on push to master; you can verify the live result with your read-only kubectl.\n- The AGENT does ALL git mechanics silently — the user may not know git, so never ask them to commit, push, pull, or open anything, and never surface git jargon. When you finish a change in ~/code: commit it ON master and push to the forgejo remote. THE COMMIT MESSAGE IS THE AUDIT TRAIL — subject says WHAT changed; body says WHY in plain words (paraphrase the user's actual request) — this matters more than the change itself. Never use [ci skip] as a non-admin (it would hide the change from the audit feed; harmless no-op applies are fine). If the push is rejected non-fast-forward, git pull --rebase forgejo master and push again. If it is rejected by branch protection (user not whitelisted), fall back to a / branch + PR via the Forgejo API (token = password field in ~/.git-credentials). Keep ~/code on a clean master when done so background auto-refresh keeps working. Tell the user in plain words what happened ('done — your change is live/recorded'). Full recipe: AGENTS.md → 'Non-admin workstation users' in ~/code.\n- Follow the engineering rules in ~/.claude/rules/ (execution, planning, quality) and every CLAUDE.md in the repo tree.\n- The monorepo is at ~/code. Non-admins get a git-crypt-LOCKED clone: secret files read as ciphertext — that is expected, not an error.", + "claudeMd": "# Viktor Barzin homelab — shared multi-user Claude Code Workstation (devvm)\n\nYou are running as a specific OS user on a SHARED devvm Workstation, not as the admin. These org-wide rules apply to EVERY user and sit at the top of settings precedence (they cannot be overridden by a user's own config):\n\n- Respect your permission tier. Your kubectl, Vault, and infra access are scoped to your RBAC tier (admin / power-user / namespace-owner). Do not attempt to escalate privileges or reach another user's resources.\n- Secrets are per-user. Never read another user's home directory, credentials, tokens, or ~/.claude secrets. Your own secrets live in your home at mode 600.\n- Infrastructure changes go through Terraform/Terragrunt — never direct kubectl apply/edit/patch. Committed stack changes are auto-applied by CI on push to master; you can verify the live result with your read-only kubectl.\n- The AGENT does ALL git mechanics silently — the user may not know git, so never ask them to commit, push, pull, or open anything, and never surface git jargon. Feature-sized work is done in an isolated git worktree (`.worktrees/`, branch `/`) and merged into master when finished, so several agents can work the same project at once — full lifecycle in ~/.claude/rules/execution.md §3; trivial single-commit fixes may go straight to master. When you finish a change in ~/code: commit it ON master and push to the forgejo remote. THE COMMIT MESSAGE IS THE AUDIT TRAIL — subject says WHAT changed; body says WHY in plain words (paraphrase the user's actual request) — this matters more than the change itself. Never use [ci skip] as a non-admin (it would hide the change from the audit feed; harmless no-op applies are fine). If the push is rejected non-fast-forward, git pull --rebase forgejo master and push again. If it is rejected by branch protection (user not whitelisted), fall back to a / branch + PR via the Forgejo API (token = password field in ~/.git-credentials). Keep ~/code on a clean master when done so background auto-refresh keeps working. Tell the user in plain words what happened ('done — your change is live/recorded'). Full recipe: AGENTS.md → 'Non-admin workstation users' in ~/code.\n- Follow the engineering rules in ~/.claude/rules/ (execution, planning, quality) and every CLAUDE.md in the repo tree.\n- The monorepo is at ~/code. Non-admins get a git-crypt-LOCKED clone: secret files read as ciphertext — that is expected, not an error.", "model": "claude-fable-5" }