From 6f0ff075b00a1ddee46f8eceabd470b636939d82 Mon Sep 17 00:00:00 2001 From: JacobPEvans <20714140+JacobPEvans@users.noreply.github.com> Date: Mon, 25 May 2026 18:16:02 -0400 Subject: [PATCH] docs: drop workspace-path assumption from plugin docs and skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #330 swapped hardcoded `~/git/...` for `${GIT_HOME_PUBLIC}//...`. Reviewer follow-up: skill docs should not bake a workspace path convention into prose either — describe what to do, not where files live. Changes (10 files): - .claude/rules/worktree-conventions.md: convention table now shows relative paths (`/main/`, `/{branch-name}/`). Operational "switch to main and sync" line drops the `cd`, says "From the main worktree, sync". - git-standards/skills/git-workflow-standards/SKILL.md: layout diagram + table use relative paths. Create/Remove commands use `../` from the main worktree. - git-workflows/skills/sync-main: "find and sync main" describes the worktree role; drops `cd`. - git-workflows/skills/troubleshoot-worktree: `git worktree add ../` (relative). - github-workflows/skills/rebase-pr: "from the main worktree" framing. - github-workflows/skills/refresh-repo: drops the `${GIT_HOME}/CLAUDE.md` citation (just "per the workspace convention"); drops the `${GIT_HOME_PUBLIC}///` path-resolution rule in favor of `git worktree list --porcelain` matching on `branch refs/heads/`; --sweep glob description loosened. - infra-orchestration/orchestrate-infra: "locate each target repo's main worktree" instead of a path glob. - infra-orchestration/sync-inventory: "from the X main worktree" framing; repo list shows names only, not paths. - infra-orchestration/test-e2e: same. - codeql-resolver/README.md: examples annotate the worktree, drop `cd`. The `${GIT_HOME}` / `${GIT_HOME_PUBLIC}` nix-home sessionVariables still exist for workspace tooling — this PR just stops mentioning them in plugin docs where they're not load-bearing. Assisted-by: Claude --- .claude/rules/worktree-conventions.md | 11 +++--- codeql-resolver/README.md | 6 ++-- .../skills/git-workflow-standards/SKILL.md | 35 +++++++------------ git-workflows/skills/sync-main/SKILL.md | 2 +- .../skills/troubleshoot-worktree/SKILL.md | 4 +-- github-workflows/skills/rebase-pr/SKILL.md | 9 +++-- github-workflows/skills/refresh-repo/SKILL.md | 22 ++++++------ .../skills/orchestrate-infra/SKILL.md | 2 +- .../skills/sync-inventory/SKILL.md | 13 +++---- infra-orchestration/skills/test-e2e/SKILL.md | 6 ++-- 10 files changed, 51 insertions(+), 59 deletions(-) diff --git a/.claude/rules/worktree-conventions.md b/.claude/rules/worktree-conventions.md index 7cf1bd7..21f99e5 100644 --- a/.claude/rules/worktree-conventions.md +++ b/.claude/rules/worktree-conventions.md @@ -9,14 +9,13 @@ default `.worktrees/` placement. ## Path Convention -```text -${GIT_HOME_PUBLIC}/{repo-name}/{branch-name}/ -``` +Per repo: main at `/main/`, every feature worktree as a sibling at +`/{branch-name}/`. Siblings are reachable as `../{branch-name}/`. Examples: -- `${GIT_HOME_PUBLIC}/claude-code-plugins/feat/add-readme-validation/` -- `${GIT_HOME_PUBLIC}/terraform-proxmox/fix/firewall-rules/` +- `claude-code-plugins/feat/add-readme-validation/` +- `terraform-proxmox/fix/firewall-rules/` ## Branch Naming @@ -26,7 +25,7 @@ Examples: ## Before Creating -1. Switch to main and sync: `cd ${GIT_HOME_PUBLIC}/{repo-name}/main && git switch main && git pull` +1. Sync main: `git pull` 2. Clean stale worktrees — a worktree is stale when it has no open PR, no uncommitted changes, and either: - A merged PR whose `headRefOid` matches local `HEAD` (`gh pr list --state merged --head {branch} --json number,headRefOid,mergedAt`) - A deleted remote (`[gone]` in `git branch -vv`) with no commits ahead of default diff --git a/codeql-resolver/README.md b/codeql-resolver/README.md index 1d2e593..0e793f7 100644 --- a/codeql-resolver/README.md +++ b/codeql-resolver/README.md @@ -149,8 +149,9 @@ codeql-resolver/ ### Example 1: Fix ci-gate.yml Permissions +In `ai-assistant-instructions`: + ```bash -cd ${GIT_HOME_PUBLIC}/ai-assistant-instructions /resolve-codeql file:.github/workflows/ci-gate.yml ``` @@ -233,8 +234,7 @@ All fixes follow these security principles: ### Local Testing ```bash -cd ${GIT_HOME_PUBLIC}/claude-code-plugins/feature/codeql-resolver/codeql-resolver -python3 scripts/test_codeql_plugin.py +python3 codeql-resolver/scripts/test_codeql_plugin.py ``` ### Adding New Alert Types diff --git a/git-standards/skills/git-workflow-standards/SKILL.md b/git-standards/skills/git-workflow-standards/SKILL.md index 751ec6d..fa6fa11 100644 --- a/git-standards/skills/git-workflow-standards/SKILL.md +++ b/git-standards/skills/git-workflow-standards/SKILL.md @@ -7,30 +7,21 @@ description: Use when managing branches, resolving merge conflicts, syncing with ## Worktree Structure -All development MUST use dedicated worktrees. Never work directly on main. +All development uses dedicated worktrees. Never work directly on main. ```text -${GIT_HOME_PUBLIC}// +/ ├── .git/ # Shared bare repo -├── main/ # Main branch (read-only for dev) -├── feature// # Feature worktrees -├── bugfix// # Bugfix worktrees -├── hotfix// # Hotfix worktrees -├── release// # Release worktrees -└── chore// # Chore worktrees +├── main/ # Main branch +├── feature// +├── bugfix// +├── hotfix// +├── release// +└── chore// ``` -| Branch Type | Branch Name | Worktree Path | -| --- | --- | --- | -| Main | `main` | `${GIT_HOME_PUBLIC}//main/` | -| Feature | `feature/add-feature` | `${GIT_HOME_PUBLIC}//feature/add-feature/` | -| Bugfix | `bugfix/bug-name` | `${GIT_HOME_PUBLIC}//bugfix/bug-name/` | -| Hotfix | `hotfix/critical-issue` | `${GIT_HOME_PUBLIC}//hotfix/critical-issue/` | -| Release | `release/1.2.0` | `${GIT_HOME_PUBLIC}//release/1.2.0/` | -| Chore | `chore/dependency-updates` | `${GIT_HOME_PUBLIC}//chore/dependency-updates/` | - -Create: `git worktree add -b ${GIT_HOME_PUBLIC}// main` -Remove: `git worktree remove ${GIT_HOME_PUBLIC}//` +Create: `git worktree add -b ../ main` +Remove: `git worktree remove ../` Every branch with commits MUST have an associated PR. Orphaned branches must get a PR or be deleted. @@ -44,7 +35,7 @@ worktrees with uncommitted changes are NEVER stale. Use `git worktree remove` (n ## Branch Hygiene -- Sync main daily: `cd ${GIT_HOME_PUBLIC}//main && git pull` +- Sync main daily: `git pull` - Long-running branches: rebase from main weekly - Before PRs: ensure branch is on latest main - Never branch from feature branches — always from main @@ -58,8 +49,8 @@ worktrees with uncommitted changes are NEVER stale. Use `git worktree remove` (n Sync main workflow: ```bash -cd ${GIT_HOME_PUBLIC}//main && git fetch origin main && git pull origin main -cd ${GIT_HOME_PUBLIC}//feature/ && git merge origin/main --no-edit +git fetch origin main && git pull origin main # in main +git merge origin/main --no-edit # in the feature worktree ``` ## Merge Conflict Resolution diff --git a/git-workflows/skills/sync-main/SKILL.md b/git-workflows/skills/sync-main/SKILL.md index 2d359eb..5936ddf 100644 --- a/git-workflows/skills/sync-main/SKILL.md +++ b/git-workflows/skills/sync-main/SKILL.md @@ -26,7 +26,7 @@ or all open PR branches when using the `all` parameter. 1. **Verify state**: `git branch --show-current`, `git status --porcelain` - STOP if on main or uncommitted changes -2. **Find and sync main**: `cd ${GIT_HOME_PUBLIC}//main && git fetch --all --prune --force && git pull` +2. **Sync main**: `git fetch --all --prune --force && git pull` (in `main/`) 3. **Check for updates**: `git fetch origin --force main` 4. **Report**: Show commits behind with `git log --oneline HEAD..origin/main` (informational only) 5. **Merge**: `git merge origin/main --no-edit` diff --git a/git-workflows/skills/troubleshoot-worktree/SKILL.md b/git-workflows/skills/troubleshoot-worktree/SKILL.md index 55bd2e9..ce88bb1 100644 --- a/git-workflows/skills/troubleshoot-worktree/SKILL.md +++ b/git-workflows/skills/troubleshoot-worktree/SKILL.md @@ -46,14 +46,14 @@ Means TWO things named `origin/main`: ### Main Worktree Not Found ```bash -git worktree add ${GIT_HOME_PUBLIC}//main main +git worktree add main main ``` ### Branch Worktree Not Found ```bash git fetch origin --force -git worktree add ${GIT_HOME_PUBLIC}// +git worktree add ../ ``` ### Branch Not Found diff --git a/github-workflows/skills/rebase-pr/SKILL.md b/github-workflows/skills/rebase-pr/SKILL.md index 6347fb0..7d749a2 100644 --- a/github-workflows/skills/rebase-pr/SKILL.md +++ b/github-workflows/skills/rebase-pr/SKILL.md @@ -72,7 +72,6 @@ that skill. ## Step 2: Sync Main ```bash -cd ${GIT_HOME_PUBLIC}/{repo}/main git fetch origin --force main git pull origin main ``` @@ -90,8 +89,8 @@ git branch {branch} origin/{branch} Create worktree and rebase: ```bash -git worktree add ${GIT_HOME_PUBLIC}/{repo}/{worktree-path} {branch} -cd ${GIT_HOME_PUBLIC}/{repo}/{worktree-path} +git worktree add ../{worktree-path} {branch} # from main/ +cd ../{worktree-path} git rebase origin/main git log --oneline origin/main..HEAD # verify commits are ahead ``` @@ -117,7 +116,7 @@ git push --force-with-lease origin {branch} ## Step 5: Fast-Forward Merge to Main ```bash -cd ${GIT_HOME_PUBLIC}/{repo}/main +cd ../main git merge-base --is-ancestor origin/main {branch} # verify FF is possible; exit 0 = yes git merge --ff-only {branch} ``` @@ -146,7 +145,7 @@ gh pr view --json state --jq '.state' # expect: MERGED ## Step 7: Cleanup ```bash -git worktree remove ${GIT_HOME_PUBLIC}/{repo}/{worktree-path} +git worktree remove ../{worktree-path} # from main/ git branch -d {branch} # use -D only after confirming state=MERGED git push origin --delete {branch} git worktree prune diff --git a/github-workflows/skills/refresh-repo/SKILL.md b/github-workflows/skills/refresh-repo/SKILL.md index 887c5d7..5340830 100644 --- a/github-workflows/skills/refresh-repo/SKILL.md +++ b/github-workflows/skills/refresh-repo/SKILL.md @@ -53,14 +53,14 @@ Replace ``, ``, `` per the placeholder legend in that sk 2. Fetch origin with stale remote branch pruning, but without tag updates: `git fetch origin --no-tags --prune --force` 3. Determine the default branch from `origin/HEAD`, falling back to `main` or `master`. -4. **Restore the default-branch worktree to the default branch.** Per the workspace - convention in `${GIT_HOME}/CLAUDE.md`, `/main/` (or `/master/`) must always - be checked out to the default branch. After a feature PR merges, that worktree is - often left on the now-`[gone]` feature branch. Detect and fix: - - Resolve the default worktree path using the workspace convention: - `${GIT_HOME_PUBLIC}///`. Do not rely on basename matching from - `git worktree list` — a feature branch named `feature/` would also - produce a path basename of ``. +4. **Restore the default-branch worktree to the default branch.** Per the + workspace convention, `/main/` (or `/master/`) must always + be checked out to the default branch. After a feature PR merges, that + worktree is often left on the now-`[gone]` feature branch. Detect and fix: + - Resolve the default worktree path from `git worktree list --porcelain`, + matching on the `branch refs/heads/` entry — do not rely on + basename matching of paths, since a feature branch named + `feature/` would also produce a path basename of ``. - If that path exists and `git -C rev-parse --abbrev-ref HEAD` does not equal `` (this is safer than `symbolic-ref --short HEAD`, which errors on detached HEAD during a rebase or commit-checkout): @@ -151,9 +151,9 @@ safety. ### `--sweep []` -Multi-repo cleanup of abandoned local branches. For each repo matching the -glob (default `${GIT_HOME_PUBLIC}/*/main/`), for every local branch where -`git log origin/main..HEAD` is non-empty: +Multi-repo cleanup of abandoned local branches. For every main worktree +in your workspace (caller can pass a custom glob if their layout differs), +for every local branch where `git log origin/main..HEAD` is non-empty: 1. **Content-equivalence check**: compute merge base, diff each touched file against current `origin/main`. If every touched file is content-equivalent diff --git a/infra-orchestration/skills/orchestrate-infra/SKILL.md b/infra-orchestration/skills/orchestrate-infra/SKILL.md index cc2482f..8f593df 100644 --- a/infra-orchestration/skills/orchestrate-infra/SKILL.md +++ b/infra-orchestration/skills/orchestrate-infra/SKILL.md @@ -39,7 +39,7 @@ Full pipeline validation: validate, plan, export inventory, syntax-check, check, ## Execution Pattern -1. **Resolve repo paths**: All repos at `${GIT_HOME_PUBLIC}//main/` +1. **Resolve repo paths**: locate each target repo locally 2. **Dispatch Terraform phase**: Launch subagent for terraform-proxmox operations 3. **Await completion**: Terraform must complete before Ansible phases 4. **Dispatch Ansible phases**: Launch parallel subagents for independent Ansible repos (invoke `superpowers:dispatching-parallel-agents`) diff --git a/infra-orchestration/skills/sync-inventory/SKILL.md b/infra-orchestration/skills/sync-inventory/SKILL.md index d0ceb33..0e535e3 100644 --- a/infra-orchestration/skills/sync-inventory/SKILL.md +++ b/infra-orchestration/skills/sync-inventory/SKILL.md @@ -17,8 +17,9 @@ Export Terraform outputs as Ansible inventory and distribute the generated inven ### 1. Export Terraform Inventory +In `terraform-proxmox`: + ```bash -cd ${GIT_HOME_PUBLIC}/terraform-proxmox/main doppler run -- terragrunt output -json ansible_inventory ``` @@ -28,11 +29,11 @@ Convert Terraform JSON output to Ansible inventory YAML format with host groups, ### 3. Distribute to Ansible Repos -Copy the generated inventory to: +Copy the generated `inventory/` into each: -- `${GIT_HOME_PUBLIC}/ansible-proxmox/main/inventory/` -- `${GIT_HOME_PUBLIC}/ansible-proxmox-apps/main/inventory/` -- `${GIT_HOME_PUBLIC}/ansible-splunk/main/inventory/` +- `ansible-proxmox` +- `ansible-proxmox-apps` +- `ansible-splunk` ### 4. Validate @@ -42,7 +43,7 @@ Run `ansible-inventory --list -i inventory/hosts.yml` in each target repo to con - Terraform state must exist (run `terragrunt apply` first) - Doppler configured with `iac-conf-mgmt` project -- All target Ansible repos must be checked out at `${GIT_HOME_PUBLIC}//main/` +- Each target Ansible repo is checked out locally ## Error Handling diff --git a/infra-orchestration/skills/test-e2e/SKILL.md b/infra-orchestration/skills/test-e2e/SKILL.md index e3e83f0..ed3dc58 100644 --- a/infra-orchestration/skills/test-e2e/SKILL.md +++ b/infra-orchestration/skills/test-e2e/SKILL.md @@ -12,15 +12,17 @@ Validates syntax, plans changes, exports inventory, and dry-runs Ansible playboo ### Stage 1: Terraform Validate +In `terraform-proxmox`: + ```bash -cd ${GIT_HOME_PUBLIC}/terraform-proxmox/main doppler run -- terragrunt validate ``` ### Stage 2: Terraform Plan +In `terraform-proxmox`: + ```bash -cd ${GIT_HOME_PUBLIC}/terraform-proxmox/main doppler run -- terragrunt plan ```