jwx-companion-bulk

# jwx-companion-bulk Apply a uniform operation across jwx companion modules (github.com/jwx-go/*). Handles cloning, branching, applying changes, verifying, committing, and reporting. ## Arguments `/jwx-companion-bulk <instructions...>` - `$INSTRUCTIONS` (required) — what to do across companion modules. Free-form text. ### Flags (parsed from instructions) - `--modules=<name,name,...>` — target only these modules (comma-separated names) - `--ref-module=<name>` — use this module as the reference/template for file-copy operations - `--pr` — push branches and create PRs (off by default; commits locally only) - `--dry-run` — show what would change without modifying anything If instructions are ambiguous, ask the user before proceeding. ## 1. Read Config 1. Read `companions.yaml` from the project root. 2. Parse the `modules` list. Each entry has: `name`, `repo`, `branch`. 3. If `--modules=` was provided, filter to only those names. Error if a name is not found. ## 2. Ensure Clones For each module in the (filtered) list: 1. If `$PROJECT/.companions/repo/<name>/` does not exist: ``` cd $PROJECT git clone <repo> .companions/repo/<name> ``` 2. If it already exists, update it: ``` cd $PROJECT/.companions/repo/<name> git fetch origin ``` 3. Determine the default branch for each module: - If `branch` is set in the config, use that. - Otherwise, read `origin/HEAD`: ``` cd $PROJECT/.companions/repo/<name> git symbolic-ref refs/remotes/origin/HEAD ``` This returns e.g. `refs/remotes/origin/develop/v4` — strip the prefix. - If `origin/HEAD` is not set, query GitHub: ``` gh repo view <org>/<name> --json defaultBranchRef --jq .defaultBranchRef.name ``` 4. Checkout the default branch: ``` cd $PROJECT/.companions/repo/<name> git checkout <default-branch> ``` ``` cd $PROJECT/.companions/repo/<name> git pull --ff-only ``` ## 3. Pre-flight Checks Run these on ALL targeted modules BEFORE modifying ANY: 1. **Clean working tree**: `git status --porcelain` must produce empty output. If any module is dirty, report which ones and STOP. 2. **Remote reachable** (only if `--pr`): `git ls-remote origin HEAD` must succeed. 3. **gh auth** (only if `--pr`): `gh auth status` must succeed. If pre-flight fails, report the failures and stop. Do not partially proceed. ## 4. Determine Execution Strategy Decide whether this is a **mechanical** or **creative** operation: - **Mechanical** (same change replicated): dependency bumps, file sync/copy, adding identical files, updating CI workflows, version string changes. - **Creative** (independent work per module): lint-fix, refactor, bug fixes, anything where changes differ per module. Heuristics: - Keywords "fix", "refactor", "lint" suggest creative. - Keywords "update", "sync", "add", "copy", "bump" suggest mechanical. When unsure, ask the user: "Same mechanical change per module, or independent work per module?" ### Mechanical: Prototype then Replicate 1. Pick first module from list (or `--ref-module` if specified). 2. Create a feature branch from the module's default branch: ``` cd $PROJECT/.companions/repo/<name> git checkout -b <branch-name> <default-branch> ``` Use ordinary branch naming: `<category>-<short-description>` (e.g. `chore-bump-jwx-dep`). 3. Apply instructions to this module. 4. Verify (if module has `go.mod`): ``` cd $PROJECT/.companions/repo/<name> go build ./... ``` ``` cd $PROJECT/.companions/repo/<name> golangci-lint run ./... ``` 5. Record exactly what changed: files modified/added/deleted, nature of change. 6. For each remaining module: a. Create feature branch (same name). b. Replicate the change, adapting module-specific values (module name in import paths, go.mod module path, etc.). c. Verify (go build + golangci-lint if has go.mod). d. If verification fails, revert (`git checkout .`), delete the branch, record failure, continue to next module. ### Creative: Parallel Subagents 1. Spawn one Agent per module, all in a single parallel block. 2. Each agent receives: - Module path: `$PROJECT/.companions/repo/<name>` - Default branch name - The instructions - Directions to: create a feature branch, do the work, verify, commit. 3. Subagents do NOT have Skill tool access. Give them explicit instructions. 4. Wait for all agents, collect results. ## 5. Commit For each module where changes were made and verification passed: 1. Stage relevant files: ``` cd $PROJECT/.companions/repo/<name> git add <files> ``` 2. Commit following standard commit message rules. ## 6. PR (only with `--pr`) For each module where changes were committed: 1. Push the feature branch: ``` cd $PROJECT/.companions/repo/<name> git push -u origin <branch-name> ``` 2. Create PR: ``` cd $PROJECT/.companions/repo/<name> gh pr create --title "<title>" --body "<body>" ``` Target the module's default branch. 3. Record PR URL. ## 7. Report Always end with a report: ``` ## Companion Module Bulk Operation Report **Operation**: <summary of instructions> **Date**: YYYY-MM-DD **Modules targeted**: N **Succeeded**: X | **Skipped**: Y | **Failed**: Z | Module | Branch | Status | PR | Notes | |--------|--------|--------|----|-------| | ... | ... | success/skipped/failed | URL or — | ... | ### Files Changed - <list of files modified across modules> ### Errors (if any) - **<module>**: <error description> ``` ## Adaptation Rules When replicating changes across modules, adapt these patterns: | Pattern | Adaptation | |---------|-----------| | Module name in `go.mod` | Read actual module path from the target's `go.mod` | | Module name in CI YAML | Package-specific test paths | | Import paths | Adjust `jwx-go/<proto>` to `jwx-go/<target>` | | Default branch | Use `branch` from `companions.yaml` for each module | | Modules without `go.mod` (benchmarks) | Skip Go-specific steps (build, lint, dep update) | ## Error Handling | Error | Response | |-------|----------| | Dirty working tree | STOP entirely (pre-flight) | | `go build` fails after change | Revert, record failure, continue others | | `golangci-lint` fails after change | Revert, record failure, continue others | | Module not applicable (e.g. no go.mod for dep update) | Skip, report "not applicable" | | PR creation fails | Report failure, branch still pushed | | Git push fails | Report, do not retry, continue others | | File already matches desired state | Report "already up to date", skip | ## Hard Rules - NEVER commit directly to default branch — always create a feature branch. - NEVER force-push. - NEVER proceed on a module with dirty working tree. - ALWAYS run pre-flight on ALL modules before modifying ANY. - ALWAYS verify `go build ./...` and `golangci-lint run ./...` before committing (for modules with go.mod). - ALWAYS report per-module results even on partial failure. - ALWAYS `cd` into `$PROJECT/.companions/repo/<name>` before running ANY command (git, go, golangci-lint) for that module. NEVER use `git -C`, `--git-dir`, or `--work-tree` instead — they don't apply to non-git tools, and the shell's working directory stays in the parent jwx repo so its git context leaks through. - NEVER use compound commands (`&&`, `||`, `;`) in Bash calls. - PRs are OFF by default. Only push/create PRs when `--pr` is specified.