Journeymen

Journeymen is a portable catalog of OpenCode agents and skills. It keeps the source collection in Git while placing only selected specialists into a repository's .opencode directory.

The catalog includes dependency-aware bundles. Installing reeve, for example, also installs its implementation, verification, review, Git, and ledger support.

Fresh Installation

Authenticate GitHub CLI, then run one bootstrap command:

gh auth login
npx --yes @arkaik01/journeymen@latest init

The bootstrap:

• installs the journeymen command globally;
• clones the private Arkaik01/journeymen catalog under ~/.local/share/journeymen;
• installs the management skill under OpenCode's default global skill directory;
• leaves catalogued agents and project skills out of global scope.

Restart OpenCode after initialization.

Interactive Management

From a project, run:

journeymen

Journeymen opens a checkbox picker. Checked bundles are the desired project state. Check a bundle to install it, uncheck one to uninstall it, then press Enter to review and confirm the changes.

The picker is divided into Primate Skills (ape, cavescribe, monkey) and the Guildhall. Selectable bundles that contain another bundle appear first, with their selectable prerequisites nested beneath them, so each bundle and its supporting agents appear only once. Scribe includes and invokes Reeve; Scrivener is standalone and only produces a Reeve-ready handoff. Supporting agents remain indented, non-selectable lines with a short role description.

Managed state is recorded in:

.opencode/journeymen.json
.opencode/journeymen.lock.json

The manifest records selected bundles. The lock records files and hashes owned by Journeymen. Uninstall keeps dependencies shared by another checked bundle and refuses to delete a managed file that has been modified locally.

Automation

Set the exact desired bundle state without opening the picker:

journeymen set --workspace C:\src\my-project --bundle reeve,testing-audit

Remove all managed bundles:

journeymen set --workspace C:\src\my-project --clear

Reapply a committed manifest after cloning a project or updating the catalog:

journeymen sync --workspace C:\src\my-project

Inspect managed state:

journeymen status --workspace C:\src\my-project

Catalog Commands

List catalog contents:

journeymen list
journeymen list --kind bundle

Capture the declared global agents and skills into this clone:

journeymen grab

grab reads ~/.config/opencode by default and never deletes the originals. Use --source-config for another config root and --force when intentionally refreshing existing catalog files.

The original copy-only command remains available for explicit or legacy use:

journeymen place --workspace C:\src\my-project --bundle reeve

Place several bundles or explicit items:

journeymen place --workspace C:\src\my-project --bundle ape,testing-audit
journeymen place --workspace C:\src\my-project --agent disputant --skill testing-audit

Existing destination files are protected. Inspect the collision and rerun with --force only when replacement is intended. --what-if is supported by grab and place. Files installed through place are not owned until the interactive manager selects a matching bundle; identical files are then adopted safely.

Update the private clone and refresh the management skill:

npm install --global @arkaik01/journeymen@latest
journeymen update

The explicit npm command upgrades installations older than 0.3.0. Starting with 0.3.0, journeymen update also refreshes the global CLI automatically.

Publishing

Run ./publish-journeymen.ps1 from PowerShell with a short-lived granular npm token that can publish the package and bypass 2FA. The script prompts without echoing the token, uses a temporary npm configuration, and removes both the configuration and process environment variable when publishing finishes.

Previewing Versions

Preview the current working tree without installing or publishing it:

./preview-journeymen.ps1

Use ./preview-journeymen.ps1 -List to see versions available in Git history, or pass one explicitly, such as ./preview-journeymen.ps1 -Version 0.3.0. Historical previews use a temporary source checkout and disposable workspace; both are removed when the picker exits. Pass -Workspace <path> only when an existing project's selected state should be shown.

Placement Map

| Catalog kind | Project destination | | --- | --- | | Agent | .opencode/agent/<name>.md | | Skill | .opencode/skills/<name>/ | | Command | .opencode/commands/<name>.md | | Tool | .opencode/tools/<name>.ts |

Restart OpenCode after placing or changing project configuration.

Project-local definitions override definitions with the same names, but unrelated global agents remain discoverable until their global files are removed or moved outside OpenCode's discovery directories. Journeymen deliberately does not make that destructive change.

Skill

The bootstrap installs skill/journeymen/SKILL.md into OpenCode's default global skill directory. No opencode.json edit is required. This management skill is global, but catalogued project skills remain local to repositories that select them.

Bootstrap Package Boundary

The public npm package's executable source contains only bin/ and lib/, plus the automatically included README.md and package.json. Agents, skills, commands, tools, and the catalog manifest remain exclusively in the private GitHub repository. GitHub CLI supplies authentication when the bootstrap clones it.

Catalog Maintenance

catalog.json is the allowlist and dependency manifest. grab copies only declared content. Supporting commands and tools are included where an agent or skill depends on them, but they are installed only through matching bundles or explicit selection.