@agentworkforce/cli 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `agentworkforce create` now opens `persona-maker@best`, supports `--to` and
+  `--save-default`, and passes `TARGET_DIR` / `CREATE_MODE` persona inputs.
+- Persona source config supports `defaultCreateTarget` for the implicit create target.
+- `--version`/`-v` now prints the CLI package version.
+
+## [0.8.0] - 2026-05-07
+
+### Added
+
+- **Add persona create mode**
+
+### Fixed
+
+- Preserve standalone persona inputs
+
+## [0.7.0] - 2026-05-07
+
+### Added
+
+- **Add persona pack install command**
+
+### Fixed
+
+- Disable scripts during persona package pack
+- Add agentworkforce version flag
+- Address persona install review feedback
+- Expand Windows home persona install paths
+
 ## [0.6.0] - 2026-05-06
 
 ### Added
@@ -60,4 +90,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Safe-path validation on persona `configFiles` materialization — rejects empty, absolute, and `..`-traversal paths so a malformed persona can't escape the mount (#23)
 - Exhaustiveness guard in `buildInteractiveSpec` so future `Harness` union additions fail at compile time rather than silently at runtime (#23)
-

package/README.md

@@ -6,20 +6,30 @@ built-in one from `/personas/`, or an installed/local one that extends a lower
 source.
 
 ```
+agentworkforce create [--to <target>] [--save-default]
 agentworkforce agent <persona>[@<tier>]
 agentworkforce list [flags]
 agentworkforce show <persona>[@<tier>]
+agentworkforce install [flags] <pkg|path>
 agentworkforce sources <list|add|remove>
 agentworkforce harness check
+agentworkforce --version
 ```
 
+- `create` — opens `persona-maker@best` for creating a new persona.
+  It resolves a target persona directory with the same source-cascade
+  constructs used by `list`, `show`, and `agent`, then passes `TARGET_DIR` and
+  `CREATE_MODE` into the persona as prompt-visible inputs.
 - `agent` — drops you into an interactive session with the harness.
 - `list` — print the persona catalog as a table (or JSON). See
   [`## List`](#list) below for every flag.
 - `show` — print the resolved spec for one persona.
+- `install` — copy persona JSON files from an npm or local persona pack into
+  the current project's fixed cwd source directory.
 - `sources` — list, add, or remove persona source directories.
 - `harness check` — probe which harnesses (`claude`, `codex`, `opencode`)
   are installed. See [`## Harness check`](#harness-check) below.
+- `--version` — print the installed package version.
 
 ## Install
 
@@ -55,9 +65,68 @@ agentworkforce agent <persona>[@<tier>]
 
 Unknown persona prints the full catalog with each entry's origin.
 
+## Create
+
+```
+agentworkforce create [--to <target>] [--save-default] [--install-in-repo]
+```
+
+`create` is the persona-authoring entry point. It runs `persona-maker@best`
+through the same interactive launch path as `agent`, including skill
+materialization, sandbox mount behavior, env/MCP resolution, and harness argv
+translation. The only extra work `create` does is resolve a target and pass it as
+persona inputs:
+
+| Input | Meaning |
+| --- | --- |
+| `TARGET_DIR` | Absolute directory where the new `<id>.json` persona file should be written. |
+| `CREATE_MODE` | `local` writes only JSON; `built-in` also updates catalog/routing/test/docs integration. |
+
+Targets:
+
+| Target | Resolves to | Create mode |
+| --- | --- | --- |
+| `cwd` | `<cwd>/.agentworkforce/workforce/personas` | `local` |
+| `user` | `~/.agentworkforce/workforce/personas` (or `AGENT_WORKFORCE_CONFIG_DIR`) | `local` |
+| `dir:n` | the nth configured persona source from `sources list` | `local` |
+| `library` | `<repo>/personas` | `built-in` |
+| path | explicit directory path | `local` |
+
+Default target resolution:
+
+1. `--to <target>` wins.
+2. If `<cwd>/.agentworkforce/workforce` exists, use `cwd`.
+3. Else use `defaultCreateTarget` from `~/.agentworkforce/workforce/config.json`.
+4. Else use `user`.
+
+`--save-default` persists the resolved target as `defaultCreateTarget` in the
+source config. This is only consulted when no cwd-local workforce directory is
+present.
+
+Examples:
+
+```sh
+# Create in the project-local persona directory when present, otherwise user dir
+agentworkforce create
+
+# Force the user persona directory
+agentworkforce create --to user
+
+# Create in a configured persona source
+agentworkforce create --to dir:1
+
+# Create in an explicit checked-out persona directory and make that the default
+agentworkforce create --to ../team-personas/personas --save-default
+
+# Create a built-in persona in this repo's /personas catalog
+agentworkforce create --to library
+```
+
 ### Examples
 
 ```sh
+agentworkforce create
+
 # Interactive code reviewer
 agentworkforce agent review@best-value
 
@@ -68,6 +137,150 @@ agentworkforce agent posthog@best
 agentworkforce agent my-posthog@best
 ```
 
+## Install persona packs
+
+```text
+agentworkforce install <pkg|path> [--persona <id> ...] [--overwrite]
+```
+
+`install` is a shadcn-style copy utility for persona JSON. It copies persona
+files into the current project's fixed cwd layer:
+`<cwd>/.agentworkforce/workforce/personas/`.
+
+Once copied, files are project-owned. Edit them directly and commit them to
+git. The CLI does not create an install ledger, lockfile, manifest, update
+command, uninstall command, diff command, or central AgentWorkforce registry.
+
+### Package and path forms
+
+Npm package specs are resolved with `npm pack`, so npm auth, npm config,
+private packages, tags, and versions work the same way they do for npm:
+
+```sh
+agentworkforce install @agentrelay/personas
+agentworkforce install @agentrelay/personas@1.2.3
+agentworkforce install @agentrelay/personas@latest
+```
+
+Local path installs read directly from the directory:
+
+```sh
+agentworkforce install ./local-personas
+agentworkforce install /absolute/path/to/local-personas
+```
+
+### Selecting personas
+
+By default, every `*.json` file in the pack's persona directory is copied.
+Use repeated `--persona <id>` flags to install a subset by persona `id`:
+
+```sh
+agentworkforce install @agentrelay/personas --persona relay-orchestrator
+agentworkforce install @agentrelay/personas --persona relay-orchestrator --persona code-reviewer
+```
+
+If any requested id is missing, the command exits non-zero before copying
+anything.
+
+### Conflicts and overwrite
+
+Target filenames are flattened into the cwd persona directory:
+
+```text
+package/personas/nested/code-reviewer.json
+  -> .agentworkforce/workforce/personas/code-reviewer.json
+```
+
+If the target file already exists, the installer reports a conflict, skips
+that file, and exits non-zero. Non-conflicting files from the same run may
+still be copied. Pass `--overwrite` to replace existing files unconditionally:
+
+```sh
+agentworkforce install @agentrelay/personas --overwrite
+```
+
+Filename collisions across packages use the same rule. The install layer does
+not namespace files by package; avoid shipping two pack files with the same
+basename if they are expected to be installed together.
+
+### Persona pack format
+
+A pack can contain multiple personas:
+
+```text
+@agentrelay/personas
+├── package.json
+└── personas/
+    ├── relay-orchestrator.json
+    ├── code-reviewer.json
+    └── e2e-validator.json
+```
+
+`package.json` may declare the persona directory:
+
+```json
+{
+  "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 use a top-level `personas/` directory.
+3. Recursively copy every `*.json` file from that directory, flattening to
+   `<cwd>/.agentworkforce/workforce/personas/<basename>.json`.
+
+Local path installs use the same metadata rules.
+
+### Relationship to sources
+
+Use `install` when this project should receive editable copies:
+
+```sh
+agentworkforce install @acme/personas
+git add .agentworkforce/workforce/personas
+```
+
+Use `sources add` when you want the cascade to point at a live directory
+without copying:
+
+```sh
+agentworkforce sources add ~/src/acme-personas/personas
+```
+
+Both feed the same cascade. `install` writes to the fixed cwd layer, while
+`sources` changes the configured source directories in
+`~/.agentworkforce/workforce/config.json`.
+
+### Author and publish a persona pack
+
+```sh
+mkdir -p acme-personas/personas
+cd acme-personas
+npm init -y
+npm pkg set name=@acme/personas version=1.0.0
+npm pkg set 'files[0]=personas' 'keywords[0]=agentworkforce-personas'
+npm pkg set agentworkforce.personas=personas
+$EDITOR personas/reviewer.json
+npm publish --access public
+```
+
+Then install it in a project:
+
+```sh
+cd ../my-project
+agentworkforce install @acme/personas --persona reviewer
+agentworkforce list --filter-tag review
+agentworkforce agent reviewer@best-value
+```
+
 ## List
 
 ```
@@ -136,6 +349,21 @@ defaults to `~/.agentworkforce/workforce/personas`. This makes installed
 personas work as plain JSON files in the default user location, or from any
 checked-out repo you add as a source directory.
 
+The same config may also carry `defaultCreateTarget`, used by `agentworkforce create`
+when no cwd-local workforce directory exists:
+
+```json
+{
+  "personaDirs": ["~/src/company-personas/personas"],
+  "defaultCreateTarget": "dir:1"
+}
+```
+
+Valid `defaultCreateTarget` values are the same values accepted by `create --to`:
+`cwd`, `user`, `dir:n`, `library`, or an explicit path. Use
+`agentworkforce create --to <target> --save-default` to write it without editing
+JSON by hand.
+
 `sources add` appends by default. `--position <n>` inserts at the 1-based
 position among configurable directories, so `--position 1` gives that directory
 the highest priority after the fixed cwd source. `sources remove` accepts either
@@ -278,6 +506,13 @@ library has no `extends`.
   "extends": "posthog",        // optional; implicit same-id if omitted
   "description": "…",          // replaces base description
   "skills": [ … ],             // replaces entire skills array
+  "inputs": {                  // prompt-visible runtime inputs; union by key
+    "TARGET_DIR": {
+      "description": "Where to write output",
+      "default": "./out",
+      "env": "MY_AGENT_TARGET_DIR"
+    }
+  },
   "env": { … },                // union, local wins per key
   "mcpServers": { … },         // union by server name, local wins per key
   "permissions": {             // allow/deny union (dedup), mode replaces
@@ -296,6 +531,167 @@ changes — `systemPrompt`, `harness`, and `harnessSettings` still come from the
 base. Use top-level `systemPrompt` if you want to replace the prompt
 uniformly across all tiers.
 
+To define a standalone local persona that does not inherit from a lower layer,
+include `intent` and a complete `tiers` object for `best`, `best-value`, and
+`minimum`. This is the shape persona packs usually ship before `install`
+copies them into the cwd layer.
+
+## Creating Personas
+
+Personas are plain JSON files. Use `agentworkforce create` when you want the
+persona-maker to draft one with the repo's conventions, or write the JSON by
+hand when the shape is simple.
+
+### Local persona
+
+Local personas live in the source cascade and do not require built-in catalog
+integration:
+
+```sh
+agentworkforce create --to user
+agentworkforce create --to cwd
+agentworkforce create --to dir:1
+```
+
+The persona maker receives `TARGET_DIR` and `CREATE_MODE=local`, so it
+should write only:
+
+```
+<target-dir>/<id>.json
+```
+
+Minimal local persona:
+
+```json
+{
+  "id": "my-reviewer",
+  "extends": "review",
+  "description": "Reviews this project with local conventions.",
+  "systemPrompt": "Focus on this repository's API compatibility rules and summarize only blocking issues."
+}
+```
+
+### Built-in persona
+
+Built-in personas live in the repo's `/personas` catalog and require full
+workload-router integration:
+
+```sh
+agentworkforce create --to library
+```
+
+The persona maker receives `CREATE_MODE=built-in`, so it should write
+`personas/<id>.json`, update the intent list/catalog registration/routing
+profile/test fixture/README, regenerate `src/generated/personas.ts`, and run
+the repo check.
+
+### Full persona file
+
+Use this when you are not extending an existing persona:
+
+```jsonc
+{
+  "id": "release-checker",
+  "intent": "release-check",
+  "tags": ["release", "review"],
+  "description": "Checks release readiness and reports blockers.",
+  "skills": [
+    {
+      "id": "prpm/npm-trusted-publishing",
+      "source": "https://prpm.dev/packages/@prpm/npm-trusted-publishing",
+      "description": "Trusted publishing and provenance setup guidance."
+    }
+  ],
+  "inputs": {
+    "PACKAGE_NAME": {
+      "description": "Package to inspect.",
+      "env": "PACKAGE_NAME",
+      "default": "."
+    }
+  },
+  "env": {
+    "NPM_TOKEN": "$NPM_TOKEN"
+  },
+  "permissions": {
+    "allow": ["Bash(npm *)"],
+    "deny": ["Bash(npm publish *)"],
+    "mode": "default"
+  },
+  "tiers": {
+    "best": {
+      "harness": "codex",
+      "model": "openai-codex/gpt-5.3-codex",
+      "systemPrompt": "Check release readiness for $PACKAGE_NAME. Produce blockers first, then evidence.",
+      "harnessSettings": { "reasoning": "high", "timeoutSeconds": 1200 }
+    },
+    "best-value": {
+      "harness": "opencode",
+      "model": "opencode/gpt-5-nano",
+      "systemPrompt": "Check release readiness for $PACKAGE_NAME. Produce blockers first, then evidence.",
+      "harnessSettings": { "reasoning": "medium", "timeoutSeconds": 900 }
+    },
+    "minimum": {
+      "harness": "opencode",
+      "model": "opencode/minimax-m2.5-free",
+      "systemPrompt": "Check release readiness for $PACKAGE_NAME. Produce only blocking issues and exact evidence.",
+      "harnessSettings": { "reasoning": "low", "timeoutSeconds": 600 }
+    }
+  }
+}
+```
+
+### Persona inputs
+
+`inputs` declare non-secret values that a launcher can pass into a persona at
+runtime. They are useful for output paths, package names, modes, and other
+prompt-visible context that should not be hard-coded into the persona.
+
+Input names must be env-style uppercase keys: `TARGET_DIR`, `PACKAGE_NAME`,
+`CREATE_MODE`. In `systemPrompt`, use `$NAME` or `${NAME}`; both forms are
+replaced before the harness starts.
+
+```jsonc
+{
+  "inputs": {
+    "TARGET_DIR": {
+      "description": "Directory where generated files should be written.",
+      "env": "MY_TARGET_DIR",
+      "default": "./out"
+    },
+    "CREATE_MODE": "local"
+  },
+  "tiers": {
+    "best": {
+      "systemPrompt": "Write the persona to $TARGET_DIR. Mode: ${CREATE_MODE}."
+    }
+  }
+}
+```
+
+Each input may be either a string shorthand or an object:
+
+| Shape | Meaning |
+| --- | --- |
+| `"NAME": "value"` | Shorthand for `{ "default": "value" }`. |
+| `description` | Human-readable explanation for `show`, docs, and catalog UIs. |
+| `env` | Env var to read when the caller did not provide an explicit value. Defaults to the input key. |
+| `default` | Literal fallback when no explicit value or env var exists. |
+
+Resolution order is strict:
+
+1. Explicit launcher value, such as the values passed by `agentworkforce create`.
+2. `process.env[env]`, or `process.env[NAME]` when `env` is omitted.
+3. `default`.
+4. If none exist, launch fails before the harness starts.
+
+Resolved inputs are substituted into the system prompt and injected into the
+child process env under the input key. They are not secrets: resolved values
+can appear in prompts, process env, logs, and agent output. Use `env` references
+instead for API keys and tokens.
+
+Local persona overlays merge `inputs` by key, so a user or project override can
+add one input without replacing all inherited inputs.
+
 ## Env references & secrets
 
 Any `env` value or `mcpServers.*.{headers,env,args,url,command}` value can be

package/dist/cli.d.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { type Harness } from '@agentworkforce/workload-router';
+export declare const CLI_VERSION: string;
+export declare const CREATE_SELECTOR = "persona-maker@best";
 /**
  * Resolve the `<harness>` placeholder used in persona systemPrompts.
  * Personas embed `<harness>` inside example install commands (e.g.
@@ -90,12 +92,27 @@ export declare function configureGitForMount(mountDir: string, patterns: readonl
 export declare function decideCleanMode(harness: Harness, installInRepo?: boolean): {
     useClean: boolean;
 };
+export interface PersonaInstallArgs {
+    source: string;
+    personaIds: string[];
+    overwrite: boolean;
+}
+export declare function parseInstallArgs(args: readonly string[]): PersonaInstallArgs;
 export declare function main(): Promise<void>;
 export interface AgentFlags {
     installInRepo: boolean;
 }
+export interface CreateFlags extends AgentFlags {
+    to?: string;
+    saveDefault: boolean;
+}
 export declare function parseAgentArgs(args: readonly string[]): {
     flags: AgentFlags;
     positional: string[];
 };
+export declare function parseCreateArgs(args: readonly string[]): {
+    flags: CreateFlags;
+    selector: string;
+    inputValues: Record<string, string>;
+};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAQA,OAAO,EAOL,KAAK,OAAO,EAMb,MAAM,iCAAiC,CAAC;AA+IzC;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AA4ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,mEAKzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,8IAajC,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AAu+BD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAqD1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAwBA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgBA,OAAO,EAOL,KAAK,OAAO,EAMb,MAAM,iCAAiC,CAAC;AA8IzC,eAAO,MAAM,WAAW,QAAuB,CAAC;AAChD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAgDpD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AA6ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,mEAKzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,8IAajC,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AAwmBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CA+B5E;AAolBD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA6D1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAwBA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACxD,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,CA4DA"}