/jwx-companion-bulk

name: jwx-companion-bulk
description: Apply bulk operations across all jwx companion modules. Args: <instructions...>

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>`