Design and implement shadcn-style persona installs

[willwashburn]

Summary

Add a project-local persona install command inspired by shadcn: users install persona packs from npm or a local path, and the persona JSON files are copied into the current project's .agentworkforce/workforce/personas/ directory so they become editable, project-owned files.

Like shadcn, this is intentionally a copy-paste utility, not a package manager. Once copied, files are yours — there is no manifest, lockfile, or install ledger. Git tracks what you have.

Primary command shape:

agentworkforce install @agentrelay/personas
agentworkforce install @agentrelay/personas@1.2.3
agentworkforce install ./local-personas
agentworkforce install @agentrelay/personas --persona relay-orchestrator
agentworkforce install @agentrelay/personas --persona relay-orchestrator --persona code-reviewer

This is distinct from sources add, which points at a live directory. install copies files into the project once, and they belong to the project.

Goals

• Allow teams to distribute multiple personas in a single npm package or local repo.
• Let a project install personas locally so they can be edited directly after install.
• Avoid maintaining a separate AgentWorkforce registry. Use npm package resolution as the registry and distribution mechanism.
• Keep persona JSON under .agentworkforce/workforce/personas/ so .agentworkforce/workforce/config.json and future workforce-level files are not scanned as personas.
• Stay narrow: copy files, refuse to overwrite by default, support --overwrite to force. No state file, no update/uninstall/diff commands, no version tracking.

Non-goals

• No install-state.json or any other install ledger. Once files are copied, they are project-owned and tracked by git — exactly like shadcn components.
• No version pinning beyond what the user passes on the command line each time.
• No update, uninstall, or diff subcommands. To update a pack, re-run install --overwrite.
• No skill validation or skill installation at install time. Skills declared in a persona's skills[] array are resolved by the harness at agent-use time, not at persona-copy time. A broken skill reference is a bug in the persona itself, fixed at the persona's definition site.

Proposed package format

A persona package can contain many persona JSON files:

@agentrelay/personas
├── package.json
└── personas/
 ├── relay-orchestrator.json
 ├── code-reviewer.json
 ├── e2e-validator.json
 └── posthog.json

Package metadata:

{
 "name": "@agentrelay/personas",
 "version": "1.2.3",
 "files": ["personas"],
 "keywords": ["agentworkforce-personas"],
 "agentworkforce": {
 "personas": "personas"
 }
}

Resolution rules:

1. Read package.json.agentworkforce.personas if present.
2. Otherwise fall back to a top-level personas/ directory.
3. Copy every *.json persona file from that directory.

Project layout after install

.agentworkforce/
└── workforce/
 ├── config.json
 └── personas/
 ├── relay-orchestrator.json
 ├── code-reviewer.json
 └── e2e-validator.json

Installed personas are project-owned editable files after install. Commit them to git like any other source file.

Install behavior

For npm packages, shell out to npm rather than implementing registry logic:

npm pack @agentrelay/personas --pack-destination <tmp>

Then:

1. Unpack the tarball into a temp directory (top-level dir is package/).
2. Read package metadata.
3. Locate the persona directory.
4. If --persona <id> flags were passed, filter the persona files down to those whose persona id matches. Repeating the flag selects multiple personas. If any requested id is not found in the package, exit non-zero with a clear error before copying anything.
5. Copy persona JSON files into .agentworkforce/workforce/personas/. Filenames are flattened — the persona file is copied directly into .agentworkforce/workforce/personas/<basename>.json, regardless of any nested layout under the package's persona directory.

Benefits of using npm pack:

• Uses npm auth and npm config automatically.
• Works with private packages.
• Supports version specifiers like @agentrelay/personas@1.2.3.
• Avoids a custom registry client.

Local path installs read directly from the directory using the same package metadata rules (or the personas/ fallback if there is no package.json).

Conflict policy (shadcn-style)

Once copied, files are yours.

• If the target file does not exist: copy it.
• If the target file exists: skip it and report a conflict, unless --overwrite is passed.
• --overwrite replaces the existing file unconditionally.

No hashing, no three-way merge, no edit detection. If you want to preserve a local edit, don't pass --overwrite. If you want the upstream version, pass --overwrite and read the diff in git.

Filename collisions across packages fall under the same rule. If @a/personas and @b/personas both ship code-reviewer.json, installing the second one on top of the first is treated identically to a local edit conflict — skipped by default, replaced with --overwrite. The install layer does not namespace files by package; the cascade keys by persona id, so the practical guidance is "don't ship two personas with the same filename if you also expect to be installed alongside each other."

Relationship to source directories

Keep both concepts:

• agentworkforce sources add <dir>: point at a live directory. Good for development against a checkout or a shared directory.
• agentworkforce install <pkg>: copy personas into this project. Good for project-owned editable personas.

Installed files participate in the existing cascade because .agentworkforce/workforce/personas/ is already the fixed cwd/project-local persona directory. install does not modify the sources config.

Acceptance criteria

• agentworkforce install @scope/pkg copies all persona JSON files from the package's persona directory into .agentworkforce/workforce/personas/.
• A package can contain multiple personas.
• The package persona directory is discovered through package.json.agentworkforce.personas, with fallback to personas/.
• The command supports npm package specs with versions (@scope/pkg@1.2.3, @scope/pkg@latest, etc.).
• The command supports local path installs (./local-personas).
• The command supports --persona <id> (repeatable) to install a subset of the personas in the pack. Unknown ids fail fast before any file is copied.
• Persona filenames are flattened into .agentworkforce/workforce/personas/<basename>.json; nested layouts inside the package's persona directory are not preserved.
• Existing persona files are not overwritten by default — the install reports conflicts and exits with a non-zero status if any target file already exists. This applies equally to filename collisions across packages.
• --overwrite forces replacement of existing files.
• Installed personas are visible to agentworkforce list and usable via agentworkforce agent <persona>.
• No install ledger, lockfile, or central registry is introduced.
• Documentation is updated in the relevant READMEs (root README.md and packages/cli/README.md at minimum) covering: the install command, version and local-path forms, --persona subset installs, --overwrite, the package format (agentworkforce.personas field and personas/ fallback), how install relates to sources, and a worked example of authoring and publishing a persona pack.

Tests to add

• Installs multiple personas from a fixture package.
• Reads agentworkforce.personas from package metadata.
• Falls back to personas/ if metadata is absent.
• Refuses to overwrite an existing persona file by default; reports the conflict.
• --overwrite replaces existing persona files.
• Local path installs work end-to-end.
• --persona <id> installs only the requested persona(s); repeating the flag installs multiple; an unknown id exits non-zero before any file is copied.
• Filenames are flattened on install (nested layouts in the package persona directory are not preserved).
• Filename collisions across two installed packages are reported as conflicts and resolved by --overwrite.
• Installed personas are loaded through the cwd/project cascade.