docs(readme): deploy v1 narrative + sandbox auth modes#89
Draft
khaliqgant wants to merge 1 commit into
Draft
Conversation
Co-Authored-By: codex via Ricky <[email protected]>
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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