Repository navigation
docs(readme): deploy v1 narrative + sandbox auth modes - #89
Conversation
Co-Authored-By: codex via Ricky <noreply@agentworkforce.com>
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe README is restructured to present deployable AI agent personas as versioned JSON configurations deployed via ChangesAgent Persona Documentation Model
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~4 minutes Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| - `packages/runtime` — deploy runtime facade and per-integration clients. | ||
| - `packages/deploy` — bundle staging and runner launch modes for `workforce | ||
| deploy`. |
There was a problem hiding this comment.
🟡 Packages section lists packages/runtime and packages/deploy which do not exist in the repository
The Packages section lists packages/runtime and packages/deploy alongside the three packages that actually exist (packages/persona-kit, packages/workload-router, packages/cli). A contributor or user reading this will assume these directories exist. Verified with ls packages/: only agentworkforce, cli, persona-kit, personas-core, and workload-router are present.
| - `packages/runtime` — deploy runtime facade and per-integration clients. | |
| - `packages/deploy` — bundle staging and runner launch modes for `workforce | |
| deploy`. | |
| - `packages/runtime` — (planned) deploy runtime facade and per-integration clients. | |
| - `packages/deploy` — (planned) bundle staging and runner launch modes for `workforce | |
| deploy`. |
Was this helpful? React with 👍 or 👎 to provide feedback.
| The great token squeeze :tm: is coming and you're probably still using opus for everything. Instead of using a sledgehammer to knock in some screws, use an agentworkforce persona to design a screwdriver. | ||
| The deploy flow validates the persona, connects declared integrations, bundles | ||
| the handler, and starts the runner. The full v1 plan is in | ||
| [`docs/plans/deploy-v1.md`](./docs/plans/deploy-v1.md). |
There was a problem hiding this comment.
🟡 Link to docs/plans/deploy-v1.md points to a non-existent file
Line 17 links to ./docs/plans/deploy-v1.md but neither the docs/ directory nor this file exist in the repository. Clicking the link from the rendered README will produce a 404.
Was this helpful? React with 👍 or 👎 to provide feedback.
| Sometimes the quickest way to understand the value of personas is to see real examples. These are intentionally verbose; useful personas tend to grow as teams capture local conventions. | ||
| The example searches Brave on a weekly cron schedule, clusters findings, and | ||
| upserts a GitHub issue. See | ||
| [`examples/weekly-digest`](./examples/weekly-digest/). |
There was a problem hiding this comment.
🟡 Links to examples/weekly-digest and examples/review-agent point to non-existent directories
The README links to examples/weekly-digest/ (line 49) and examples/review-agent/ (line 91) as working examples, and the Quick Start section instructs users to workforce deploy ./examples/weekly-digest/persona.json. The examples/ directory only contains openclaw-routing.ts and tsconfig.json — neither directory exists. Users following the Quick Start will immediately hit a file-not-found error.
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
Summary
Reframe the top-level README around
workforce deployand personas-as-deployable-agents, and document BYO vs workforce-managed sandbox auth in the quick-start while example READMEs are still owned by sibling scaffolding.Spec
Resolves part of:
workforce/docs/plans/deploy-v1.mdTrack: B in
workforce/docs/plans/deploy-v1-workflow-spec.md(README-focused subsliceupdate-readme)Sibling PRs
Acceptance
workforce deployas primary product.## Local agents.examples/weekly-digest/README.mddocuments both sandbox auth paths.examples/review-agent/README.mddocuments both sandbox auth paths.pnpm run checkgreen.Gaps
examples/weekly-digest/README.mdandexamples/review-agent/README.mdwere not created because the example directories are absent in this slice worktree; they are owned by the sibling example scaffolding slice../docs/plans/deploy-v1.md,./examples/weekly-digest/, and./examples/review-agent/.Validation
corepack pnpm install --frozen-lockfilepassed with no lockfile changes.corepack pnpm run lintfailed before local package artifacts existed;corepack pnpm -r buildpassed, thencorepack pnpm run lintpassed.corepack pnpm run typecheckpassed.corepack pnpm run testpassed.corepack pnpm run checkpassed.Diff evidence
$ git diff --stat origin/main...codex/deploy-v1-readme README.md | 695 ++++++++++++-------------------------------------------------- 1 file changed, 133 insertions(+), 562 deletions(-)-To create a project-specific persona, run:
+Run the same persona in a Daytona sandbox with either workforce-managed auth:
-This opens the internal
persona-makersystem persona. By default, the new-persona is saved to
./.agentworkforce/workforce/personas(created if needed).+Or bring your own Daytona key:
-## Inside a persona
-A persona is a JSON file. Top-level fields apply to every tier; the
tiersblock holds per-tier overrides.systemPromptharness+modelclaude/codex/opencode) and which modelskillsscope/name); installed at launch into the right harness directorymcpServerspermissionsmounttiersbest,best-value,minimum— depth and cost dial; same correctness bar-Tiering controls depth, latency, and cost — not the quality bar. A routing profile layers on top: policy-only, selects which persona tier to use per intent.
+For local iteration, run it in dev mode:
-Codex-backed tiers can request Codex launch policy in
harnessSettings. Use-
"sandboxMode": "workspace-write"with"workspaceWriteNetworkAccess": true-when the persona must run shell commands with outbound network access, such as
-registry discovery via
npx, while keeping filesystem writes sandboxed.+
bash +BRAVE_API_KEY=... workforce deploy ./examples/weekly-digest/persona.json --dev +-## Examples
-Sometimes the quickest way to understand the value of personas is to see real examples. These are intentionally verbose; useful personas tend to grow as teams capture local conventions.
+The example searches Brave on a weekly cron schedule, clusters findings, and
+upserts a GitHub issue. See
+
examples/weekly-digest.-### Next.js marketing website agent
-A persona specifically for a Next.js marketing surface. This local overlay
-inherits the generic frontend implementer from
@agentworkforce/personas-core,-switches tiers to Claude so MCP and tool permissions are enforced today, and
-attaches a browser MCP for visual checks. File scope is handled by the Relayfile
-
mountblock.+## What a persona looks like
{ - "id": "nextjs-marketing", - "extends": "frontend-implementer", - "description": "Builds and edits the marketing surface of a Next.js app with SEO, accessibility, and visual QA in scope.", - "mcpServers": { - "browser": { - "type": "stdio", - "command": "npx", - "args": ["-y", "@playwright/mcp@latest", "--browser", "chrome"] + "id": "review-agent", + "intent": "review", + "tags": ["review"], + "description": "Reviews opened PRs, responds to @mentions, and comments on red CI.", + "cloud": true, + "useSubscription": true, + "integrations": { + "github": { + "triggers": [ + { "on": "pull_request.opened" }, + { "on": "issue_comment.created", "match": "@mention" } + ] + }, + "slack": { + "triggers": [{ "on": "app_mention" }] } }, - "permissions": { - "allow": [ - "Bash(npm run lint)", - "Bash(npm run typecheck)", - "Bash(npm run build)", - "mcp__browser" - ], - "deny": [ - "Bash(rm -rf *)", - "Bash(npm publish *)" - ], - "mode": "default" - }, - "mount": { - "readonlyPatterns": [ - "*", - "!app/", - "!app/(marketing)/", - "!app/(marketing)/**", - "!app/page.tsx", - "!components/", - "!components/marketing/", - "!components/marketing/**", - "!public/", - "!public/**" - ] - }, - "systemPrompt": "You own only the Next.js marketing surface. Work inside app/(marketing), app/page.tsx, components/marketing, and public assets unless the user explicitly expands scope. Preserve existing design-system conventions, metadata, structured data, responsive behavior, accessibility, and Core Web Vitals. Use the browser MCP for visual inspection before completion when a page changes. Output contract: changed files, visual checks performed, commands run, and any SEO or accessibility risks left open.", + "sandbox": true, + "memory": { "enabled": true, "scopes": ["session", "workspace"] }, + "onEvent": "./agent.ts", "tiers": { - "best": { - "harness": "claude", - "model": "claude-opus-4-6", - "harnessSettings": { "reasoning": "high", "timeoutSeconds": 1200 } - }, "best-value": { - "harness": "claude", - "model": "claude-sonnet-4-6", - "harnessSettings": { "reasoning": "medium", "timeoutSeconds": 900 } - }, - "minimum": { - "harness": "claude", - "model": "claude-haiku-4-5-20251001", - "harnessSettings": { "reasoning": "low", "timeoutSeconds": 600 } + "harness": "codex", + "model": "gpt-5.4", + "systemPrompt": "Review PRs for correctness, risk, and missing tests.", + "harnessSettings": { + "reasoning": "medium", + "timeoutSeconds": 1200 + } } } }-
bash -npx agentworkforce agent nextjs-marketing@best-value -+The
onEventfile exports the handler that decides what to do when a cron tick,+GitHub event, Linear issue, Slack mention, Notion update, or Jira event arrives.
+See
examples/review-agentfor a complete example.-### Code Reviewer
-Tune the core-pack reviewer for a repo where API compatibility and migration
-risk matter more than style commentary. Install
@agentworkforce/personas-core-first so
code-reviewerexists in a lower source layer.+## Run modes
-```json
-{
-}
-```
+
workforce deploy <persona-path>defaults to the best available runner mode.-
bash -agentworkforce agent api-reviewer@best-value -+| Mode | Use it for |
+| --- | --- |
+|
--dev| Local long-lived iteration. The bundled runner executes on your machine and streams logs. |+|
--sandbox| Daytona-backed execution with the bundle uploaded into a sandbox. |+|
--cloud| Reserved for the hosted deploy endpoint. The flag exists, but hosted deploy lands after the v1 local/sandbox slice. |-### Documentation writer
-Add a project-specific writer that inherits the technical writer persona, but
-binds the docs target through a prompt-visible input. Install
-
@agentworkforce/personas-corefirst sotechnical-writerexists in a lower-source layer.
+You can also use
--bundle-out <dir>to stage the bundle without launching it,+or
--dry-runto validate schema, triggers, and integration readiness.-```json
-{
-}
-```
+## Integrations supported
-
bash -DOCS_PATH=docs/api.md agentworkforce npx agent docs-writer@best-value -+Deploy v1 targets the Tier-1 Relayfile providers:
-> [!note]
-> Put each persona JSON file at
./.agentworkforce/workforce/personas/<id>.jsonor create it withagentworkforce create. You can keep Relayfile mount rules in the persona JSONmountblock, or in project-root.agentignore/.agentreadonlydotfiles. Launch withagentworkforce agent <id>@<tier>.+| Provider | Typical triggers |
+| --- | --- |
+| GitHub |
pull_request.opened,issue_comment.created,check_run.completed|+| Linear |
issue.created,issue.updated,comment.created|+| Slack |
app_mention, channel messages, reactions |+| Notion | page, database, block, and comment updates |
+| Jira | issue, comment, project, and sprint updates |
-## CLI
+Persona-kit ships a trigger registry for linting. Unknown trigger names warn
+instead of failing deploy, because the cloud runtime remains the source of
+truth.
-The
agentworkforcecommand is the fastest way to actually run a persona. It resolves personas from project-local files, configured source directories, and the small internal built-in catalog, installs any declared skills, and execs the harness CLI (claude,codex, oropencode) with the right model, system prompt, env vars, MCP servers, and permissions wired up.+## Local agents
-### Install
+Personas still work as local harness configs. A local persona chooses the coding
+agent, model, reasoning settings, skills, MCP servers, sidecar prompts,
+permissions, and file visibility rules for an interactive session.
-From npm (recommended):
+Install a first-party persona pack, then run one of its personas:
-That puts the
agentworkforcecommand on your PATH.-From the monorepo checkout:
+Create a project-specific persona:
-(Or run the built bin directly:
./packages/cli/dist/cli.js ….)+This opens the internal
persona-makersystem persona. By default, new personas+are saved to
./.agentworkforce/workforce/personas.-### Usage
+Common local commands:
-
-agentworkforce create [--save-in-directory=<target>] [--save-default] [--install-in-repo] [--no-launch-metadata] -agentworkforce agent [--install-in-repo] [--no-launch-metadata] <persona>[@<tier>] +text+agentworkforce create [--save-in-directory=] [--save-default]
+agentworkforce agent [--install-in-repo] [@]
agentworkforce list [flags]
agentworkforce install [flags] <pkg|path>
agentworkforce sources <list|add|remove>
@@ -229,117 +153,35 @@ agentworkforce harness check
agentworkforce --version
The command copies matching
*.jsonpersona files into-
./.agentworkforce/workforce/personas/, flattening nested package paths to-plain filenames. Existing files are skipped and reported as conflicts by
-default; pass
--overwriteto replace them:+
./.agentworkforce/workforce/personas/. Existing files are skipped by default;+pass
--overwriteto replace them.-
bash -agentworkforce install @agentrelay/personas --overwrite -+Package layout:
-Persona packs use npm as the distribution mechanism. A package can point at
-its persona directory with
package.jsonmetadata, or fall back to a top-level-
personas/directory:+```text
+@acme/personas/
+├── package.json
+└── personas/
+```
{ @@ -353,168 +195,35 @@ its persona directory with `package.json` metadata, or fall back to a top-level }-```text
-@acme/personas/
-├── package.json
-└── personas/
-```
-First-party examples:
+First-party packages:
@agentworkforce/personas-coreis owned in this repo and contains genericpersonas such as
code-reviewer,frontend-implementer,verifier, andtest-strategist.--
@agentrelay/personasis owned by the Relay repo and contains Relay-specificrelay-orchestrator.-
persona-makerremains part of the internal built-in distribution. You do not-need to install
@agentworkforce/personas-corebefore running-
agentworkforce create.-
installis a copy utility. Use it when a project should own and edit its-persona files.
sources add <dir>is separate: it points the cascade at a live-directory and does not copy files.
-Worked authoring flow:
-
bash -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 -cd ../my-project -agentworkforce install @acme/personas --persona reviewer -git add .agentworkforce/workforce/personas/reviewer.json --### Local persona override
-Project-local
./.agentworkforce/workforce/personas/api-reviewer.json:-```json
-{
-}
-```
-This inherits from an installed lower-layer
code-reviewerpersona, then-layers project-specific instructions on top.
-The full docs — cascade rules,
${VAR}interpolation, MCP transport-options, permission grammar, troubleshooting — live in
-packages/cli/README.md.
-### Skill staging (interactive claude only)
+-
@agentrelay/personasis owned by the Relay repo and containsrelay-orchestrator.-Interactive
claudesessions stage skills outside the repo by default.-The CLI materializes a Claude Code plugin under the user's home directory
-and passes it via
--plugin-dir, so the session sees exactly the persona's-declared skills — and nothing the repo happens to have in
.claude/skills/.-```
-~/.agentworkforce/workforce/
-└── sessions/--/
-```
-On exit the whole stage dir is removed with a single
rm -rf. To fall back-to the legacy behavior and install into the repo's
.claude/skills/, pass-
--install-in-repo:-
bash -agentworkforce install @agentworkforce/personas-core --persona code-reviewer -agentworkforce agent --install-in-repo code-reviewer@best --V1 scope: claude interactive only. codex and opencode still use the
-repo-relative install path. A content-addressed
~/.agentworkforce/workforce/cache/-layer for reusing installs across sessions is planned but not yet wired up. See
-packages/cli/README.md#skill-staging
-for the full mechanics.
-### Sandbox mount (default for claude / opencode)
-Interactive
claudeandopencodesessions launch inside a-
@relayfile/local-mount-sandbox by default. The mount hides repo-level harness configuration
-(claude) and routes skill-install writes into the sandbox (opencode), so
-the model sees persona context + user-level context — and nothing the
-repo itself declares. The mount also enforces Relayfile rules from the
-persona's
mountblock plus project-local.agentignore,.agentreadonly,-
.<personaId>.agentignore, and.<personaId>.agentreadonly. Codex sessions-never mount.
CLAUDE.md(at any depth)~/.claude/CLAUDE.md(user-level)CLAUDE.local.md~/.claude/skills/(user-level skills).claude/--plugin-dir).mcp.jsonmcpServersblock-Run
agentworkforce agent <id>@<tier>for any installed/local persona.-The repo tree is mirrored into
~/.agentworkforce/workforce/sessions/<id>/mount/;-the harness sees the mount as its cwd. Writes inside the mount sync back to
-the real repo on exit unless the path is ignored or read-only by Relayfile
-rules. Ignore and read-only semantics follow gitignore —
.claudehides-nested variants like
packages/foo/.claude/too..gitis included in the-mount (one-way project→mount sync) so git commands work inside the sandbox;
-mount-side commits are discarded on cleanup, so push to persist work.
-Opt out:
--install-in-reporuns against the real cwd and stages-skills into the repo's harness-conventional dirs. Useful when you want to
-inspect installed skills on disk or when the mount conflicts with
-something else (network filesystem, etc.).
-Caveat: user-level harness config in
~/.claude/etc. still loads-inside the session — the mount hides the repo's context, not the
-user's. If you need to hide user-level config too, launch under a scratch
-
$HOME. See packages/cli/README.md#sandbox-mount-for the full mount layout and semantics.
+The full local CLI docs, cascade rules, MCP transport options, permission
+grammar, skill staging, and sandbox mount behavior live in
+
packages/cli/README.md.Packages
--
packages/workload-router— TypeScript SDK for typed persona + routing profile resolution (harness-agnostic).--
packages/persona-kit— Composable primitives for launching a persona's harness: env-ref resolution, MCP server translation, per-harness argv building. The layer the CLI sits on top of. Depend on this directly if you're building your own orchestrator on top of@agentworkforce/workload-routerand want the same behaviors.--
packages/cli— command-line implementation used by theagentworkforcewrapper: spawn a persona's harness (claude/codex/opencode) from the shell. See packages/cli/README.md for the full docs, and the CLI section below for a quick tour.-## Personas
--
personas/persona-maker.json-The built-in catalog is intentionally limited to required internal/system
-personas. Optional reusable personas are distributed through persona packs:
--
packages/personas-core/personas/*.jsonpublishes as@agentworkforce/personas-core.-- Relay-specific personas are owned by the Relay repo and publish as
@agentrelay/personas.-## Routing profiles
--
packages/workload-router/routing-profiles/default.json--
packages/workload-router/routing-profiles/schema.json+-
packages/persona-kit— composable primitives for parsing personas,+-
packages/workload-router— TypeScript SDK for typed persona and routing+-
packages/cli— command-line implementation used by theagentworkforce+-
packages/runtime— deploy runtime facade and per-integration clients.+-
packages/deploy— bundle staging and runner launch modes for `workforceTypeScript SDK usage
-For internal system personas, the recommended entry point is
-
usePersona(intent)— a synchronous, side-effect-free factory that resolves-a persona and returns grouped install metadata. Calling it does nothing but
-pre-compute the routing; nothing is installed or spawned until you run the
-install command yourself. Optional pack/local personas should be resolved
-through the CLI/source cascade and passed to
useSelectionor-
materializeSkillsForas resolved selections.+For internal system personas, use
usePersona(intent)to resolve a persona and+pre-compute install metadata. It is synchronous and side-effect free.
-> Despite the
use*prefix,usePersonais not a React hook. It is a-> plain synchronous factory with no implicit state — safe to call anywhere.
-The full return shape is:
-
ts -const { selection, install } = usePersona('persona-authoring'); ---
selection: resolved persona choice and runtime metadata.--
install: grouped install metadata.--
install.plan: pure skill-install plan with no side effects.--
install.command: full install command as an argv array.--
install.commandString: full install command as a shell string.--
install.cleanupCommand/install.cleanupCommandString: removes the-For the underlying primitives —
resolvePersona,materializeSkillsFor,-and friends — see
-
packages/workload-router/README.md.-## OpenClaw integration pattern
-1. Map user request to
intent:implement-frontendreviewarchitecture-planrequirements-analysisdebuggingsecurity-reviewdocumentationverificationtest-strategytdd-enforcementflake-investigationopencode-workflow-correctnessnpm-provenanceposthog-2. Call
usePersona(intent, { profile? })only for internal built-in personas.-3. Run
install.commandStringto materialize the persona's skills into theselection.runtime. TheagentworkforceCLI is the reference implementation of step 3 — seepackages/cli/src/cli.ts.-
resolvePersonaremains the lower-level resolver for internal built-ins.-
useSelectionandmaterializeSkillsForare the lower-level primitives for-already-resolved pack/local persona selections.
-See runnable mapping example:
--
examples/openclaw-routing.ts-This keeps runtime configuration in personas, while routing policy stays explicit, typed, and auditable.
-## Skills on personas
-A persona can declare a
skillsarray of reusable capability packages (e.g. from prpm.dev):-```json
-"skills": [
-]
-```
-Persona JSON is harness-agnostic — it declares what skill is needed, not how to install it. The SDK's
materializeSkills(skills, harness)/materializeSkillsFor(selection)helper turns the declaration into a concrete install plan, routing each skill to the right on-disk convention per harness:claudeprpm install --as claude.claude/skills/codexprpm install --as codex.agents/skills/opencodeprpm install --as opencode.agents/skills/-Each returned
SkillInstallcarries an argv-styleinstallCommand,installedDir, andinstalledManifestpath. The helper is pure — it never shells out or touches disk — so callers (relay workflows, OpenClaw spawners, ad-hoc scripts) decide how to execute it. Once installed, Claude Code auto-discovers skills from.claude/skills/; for other harnesses, read the manifest off disk and inject it into the agent's task body.-## Eval framework (scaffold direction)
-Next step is a benchmark harness to score persona/tier combinations on:
-- quality (task pass rate)
-- cost
-- latency
-Then publish a versioned “recommended tier map” so default routing is data-backed.
-## Quick start
-
bash -corepack enable -pnpm install -pnpm run check --This runs minimal guardrails across the workspace:
--
lint(currently TypeScript-only)--
typecheck(package + examples)--
test(Node test runner)-## Developing
-For iterating on the CLI, persona-kit, workload-router, or internal system persona JSON files,
-use the watch-mode dev loop instead of rebuilding by hand.
-Terminal 1 — start the watchers (leave running):
-
bash -npm run dev --First runs a cold
corepack pnpm -r buildso every package'sdist/exists,-then starts
tsc --watchon all three packages in parallel. For-
workload-routerit also runs a persona-JSON watcher: editing any internal-system file under
/personas/*.jsonregenerates-
packages/workload-router/src/generated/personas.ts, and tsc picks up the-change and rebuilds dist automatically — full JSON → built artifact flow with
-no manual step.
-Terminal 2 — invoke the CLI against the latest build:
-
bash -npm run dev:cli -- harness check -npm run dev:cli -- agent code-reviewer@best-value "look at the diff on this branch" --The
--is required so npm forwards everything after it as argv to the CLI-(otherwise npm consumes flags like
--modelfor itself).-Edit → save → re-run in terminal 2. TypeScript errors show up in terminal 1.
-Per-package dev: if you only want to watch one package, run
-
corepack pnpm --filter @agentworkforce/<name> run dev(where<name>is-
cli,persona-kit, orworkload-router).+For lower-level primitives, see
+
packages/workload-router/README.md.Generated by Ricky workflow
workforce-deploy-v1