Uh oh!
There was an error while loading. Please reload this page.
feat(persona-maker): mount/MCP/sidecar guidance via agentsMd sidecar - #108
Merged
Conversation
persona-maker.json's AGENTS.md sidecar only listed `mount` and
`mcpServers` as optional fields without explaining when to use them,
the shape, or how harness selection is constrained by MCP support.
Authored personas needing filesystem sandboxing or MCP wiring were a
coin-flip on getting these blocks right.
- Add a `mount` section covering ignoredPatterns/readonlyPatterns
semantics, the `.{persona.id}.agentignore` overlay behavior keyed off
`agentName: persona.id`, the gitignore-negation idiom for allow-lists,
the file-scope-vs-tool-scope split from `permissions`, and the
auto-`.git` sandbox behavior.
- Add an `mcpServers` section with the two spec variants (http/sse vs
stdio), an example of each, `$VAR` substitution policy, and the
claude / codex / opencode support matrix so harness selection is
informed when MCP is required.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>Contributor
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR externalizes the persona authoring specification from an inline ChangesPersona authoring specification
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
…ills The mount and MCP additions from the previous commit made agentsMdContent even longer. Extract them — plus the silent-footgun guidance about claudeMdContent vs claudeMd — into three local skill .md files matching the proactive-agents skill-loading pattern. The skills install into the session via the local source-kind, so the persona reads them as standalone SKILL.md files in its working dir instead of carrying everything inline. Skills: - personas/skills/relayfile-mount.md — mount field deep dive: allow-list idiom (/* not **, paired !dir/ + !dir/**), readonlyPatterns scope rule (never the work dir), agentName overlay, .git sandbox behavior. - personas/skills/persona-mcp-servers.md — mcpServers two variants (http/sse vs stdio), $VAR substitution, claude/codex/opencode support matrix, permissions.allow pairing. - personas/skills/persona-sidecars.md — claudeMd (path) vs claudeMdContent (inline) distinction; calls out that the dry-run does NOT catch a path string mistakenly stored in *MdContent. persona-maker.json: - skills[] now declares the three local skills alongside skill.sh/find-skills. - agentsMdContent trimmed: the long mount/MCP/sidecar paragraphs are replaced with one-line skill pointers. Net length: 15985 → 15318 chars. - Anti-goals extended with the four lessons from a recent broken persona: filename string in *MdContent; ** as broad mount exclude; readonly on work dir; opencode + mcpServers; bare model alias without version. - Added 'full model identifiers' rule (claude-sonnet-4-6, not claude-sonnet). Regenerated packages/workload-router/src/generated/personas.ts to pick up the new skills. Dry-run: ✓ 4 skill(s) installed cleanly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The "obvious" gitignore allow-list `["/*", "!web/", "!web/**"]` silently
produces an empty mount. Reproduced against relayfile's createMount:
mount root contained only CLAUDE.md, _MOUNT_README.md, and .relayfile-local-mount
— no web/.
Root cause in relayfile-local-mount/src/mount.ts isPathMatched():
return matcher.ignores(relPath) || (isDirectory && matcher.ignores(`${relPath}/`));
The OR short-circuits. For a directory `web`:
- matcher.ignores('web') → true (`/*` matches the bare name)
- matcher.ignores('web/') → false (`!web/` negates the trailing-slash form)
but this branch is never reached.
So `!web/` (slash) only counters the trailing-slash form, leaving the
bare-name check unopposed. The walker treats `web` as ignored and skips
recursion. Verified by harness:
/* + !web/ + !web/** → web (dir) reported as ignored: true (broken)
/* + !web + !web/** → web (dir) reported as ignored: false (correct)
Confirmed end-to-end against a real createMount: with `!web` the mount
root contains web/content/post.md as expected.
Updates:
- relayfile-mount.md skill: add a fourth rule explicitly calling out the
`!dir` vs `!dir/` distinction with the walker's short-circuit as the
reason, plus a "wrong / right" side-by-side. Update the checklist line.
- persona-maker.json anti-goal: replace `!dir/` reference with `!dir`
plus the reason.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
personas/skills/relayfile-mount.md (1)
32-33: 💤 Low valueConsider clarifying the placeholder notation.
The
.{id}notation could be more explicit that it's a placeholder. For an AI agent consuming this skill, consider using.${id}or adding a concrete example like "For a persona withid: blog-writer, the dotfile would be.blog-writer.agentignore."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@personas/skills/relayfile-mount.md` around lines 32 - 33, The placeholder notation `.{id}.agentignore` and `.{id}.agentreadonly` is ambiguous; update these entries to use a clearer placeholder like `.${id}.agentignore` and `.${id}.agentreadonly` or add a concrete example line (e.g., for `id: blog-writer` show `.blog-writer.agentignore`) so readers and agents understand that `{id}` is substituted with the persona id.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@personas/skills/relayfile-mount.md`:
- Around line 32-33: The placeholder notation `.{id}.agentignore` and
`.{id}.agentreadonly` is ambiguous; update these entries to use a clearer
placeholder like `.${id}.agentignore` and `.${id}.agentreadonly` or add a
concrete example line (e.g., for `id: blog-writer` show
`.blog-writer.agentignore`) so readers and agents understand that `{id}` is
substituted with the persona id.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 51803e8c-d30a-4235-a2b0-74028ad47bff
⛔ Files ignored due to path filters (1)
packages/workload-router/src/generated/personas.tsis excluded by!**/generated/**
📒 Files selected for processing (4)
personas/persona-maker.jsonpersonas/skills/persona-mcp-servers.mdpersonas/skills/persona-sidecars.mdpersonas/skills/relayfile-mount.md
✅ Files skipped from review due to trivial changes (2)
- personas/skills/persona-sidecars.md
- personas/skills/persona-mcp-servers.md
🚧 Files skipped from review as they are similar to previous changes (1)
- personas/persona-maker.json
The previous extraction-into-local-skills approach was broken in the field. Reported live: persona-maker spawned from a non-workforce cwd (e.g. ../relay) only loaded `find-skills` — the three local skills `relayfile-mount`, `persona-mcp-servers`, `persona-sidecars` were missing from opencode's Skills picker. Two layered bugs: 1. The agentworkforce binary on PATH is the published 3.0.3 from npm. Its baked-in catalog has the old persona-maker (only find-skills). New skills aren't visible until a release lands. 2. Even with the local CLI build, local skill sources resolve relative paths against process.cwd() at install time. When invoked from `/tmp/` or any non-workforce repo, `cp personas/skills/<x>.md ...` fails because the .md files only exist in the workforce source repo. Three of four skill installs fail with exit code 1. The proactive-agents pattern (local/<name> source paths) works there because both the persona AND its skill .md files are co-located in the same user-repo. Persona-maker is a BUILT-IN shipped via npm — that pattern doesn't carry across. Fix: use the agentsMd path-form sidecar. The catalog generator at `packages/workload-router/scripts/generate-personas.mjs` already inlines sidecar .md content into agentsMdContent at build time, so the published package ships a single bundled spec. The .md file is a real markdown file the author can edit ergonomically; the user sees the full content in AGENTS.md at session start with no runtime filesystem lookups required. Changes: - New: personas/persona-maker.md — full operating spec including the Relayfile mount, MCP servers, and Persona sidecar sections that were previously split into local skill files. Same content the generator would have inlined; consolidated into one file because cross-cwd resolution made splitting unworkable. - personas/persona-maker.json: replace agentsMdContent (inline) with agentsMd (./persona-maker.md). Drop the three local/ skill entries from skills[]; only skill.sh/find-skills remains. - Delete personas/skills/* — content lives in persona-maker.md now. - Regenerated packages/workload-router/src/generated/personas.ts; agentsMdContent now 25,371 chars with all three sections inlined. Verified: dry-run green from /tmp (non-workforce cwd) — the cross-repo case that previously produced 3 of 4 failed installs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…m.dev Previous iterations tried inlining everything in agentsMdContent and then extracting to local skill .md files referenced via repo-relative paths. The local-path approach broke cross-repo invocation because local skill sources resolve against process.cwd() at install time, not the workforce package install root. Confirmed live: persona-maker spawned from /Users/khaliqgant/Projects/AgentWorkforce/relay only saw skill.sh/find-skills in the opencode picker. Fix: publish the three skills as prpm packages so they're installable from any cwd via npx -y prpm install <ref>. Package layout (personas/skills/): - prpm.json — multi-package manifest following the @prpm/prpm-json-best-practices-skill structure: top-level metadata (name, version, author, license, repository, organization), plus a packages[] with three skill entries (format: generic, subtype: skill). - LICENSE — MIT, picked up automatically by prpm publish for all packages. - README.md — discovery / install docs. - persona-relayfile-mount/SKILL.md — mount field deep dive: allow-list idiom, !web vs !web/ walker gotcha, readonlyPatterns scope, agentName overlay, .git sandbox. - persona-mcp-servers/SKILL.md — mcpServers spec variants, $VAR substitution, claude/codex/opencode harness matrix, permissions.allow pairing. - persona-sidecars/SKILL.md — claudeMd (path) vs claudeMdContent (inline) distinction; the silent footgun the dry-run does NOT catch. persona-maker.json: - skills[] now declares the three @agent-workforce/persona-* refs alongside skill.sh/find-skills. They install via prpm at session start and appear in the opencode Skills picker. - agentsMd: ./persona-maker.md — slim sidecar restored, with the three embedded sections replaced by pointers to the published skills. Anti-goals updated to reference the new skill IDs. Regenerated packages/workload-router/src/generated/personas.ts. `prpm publish --dry-run` from personas/skills/: ✓ all 3 packages ready to publish under @agent-workforce/ scope (khaliqgant ✓ as org member). Publish runs separately (user-driven, not automated in this commit). After publish lands on prpm.dev, `agentworkforce agent persona-maker --dry-run` will install all four skills cleanly. Until then the dry-run exercising the three new skills will fail at the prpm registry lookup step — expected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…works Published 1.0.0 with format: generic. Install via `npx -y prpm install @agent-workforce/persona-relayfile-mount --as opencode` (the command persona-kit emits for opencode-harness personas) errors with: Failed to parse generic format: Unsupported source format for conversion: generic prpm has format converters keyed off the source format. `generic` has no converter to `opencode` / `codex` / etc., so install fails the moment the workforce CLI tries to materialize the skill. Bump to 1.0.1 with format: claude. SKILL.md with YAML frontmatter is canonically claude-flavored, and prpm knows how to convert claude → opencode (verified by installing @agent-relay/choosing-swarm-patterns with --as opencode: ✓ Converted from claude to opencode). Dry-run validates clean for all three packages at 1.0.1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…eneric Verified after publish: `prpm show @agent-workforce/persona-relayfile-mount` returns "Type: generic skill" at version 1.0.1, and `prpm install --as opencode` still errors "Failed to parse generic format". Either the publish of 1.0.1 happened before the format-change commit landed in the working tree, or prpm caches format metadata at first publish — either way, the remote tarball is still generic. Bump to 1.0.2 with format: claude. Dry-run confirms: Package: @agent-workforce/persona-relayfile-mount@1.0.2 Format: claude | Subtype: skill Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The prpm registry route now updates mutable manifest fields on republish (format, subtype, description, tags, etc.), so the three skills finally landed as format: claude. Verified end-to-end: - `prpm show @agent-workforce/persona-relayfile-mount` reports Type: claude skill at v1.0.3 (previously locked at generic from 1.0.0). - `agentworkforce agent persona-maker --dry-run` from /tmp: ✓ dry-run ok: 4 skill(s) installed cleanly. All three new skills now convert claude → opencode and materialize into .opencode/skills/ at session start. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
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 freeto 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
The persona-maker built-in was missing teaching content for
mount,mcpServers, and the silent-footgun distinction betweenclaudeMd(path) andclaudeMdContent(inline). A persona authored against the existing spec hit four real failure modes:claudeMdContent: \"web-blog-content-writer.claudeMdContent.md\"— filename string written verbatim as CLAUDE.md body (dry-run green, agent boots with no spec).mount.ignoredPatterns: [\"**\", \"!./web/**\"]—**breaks!re-includes; empty mount.readonlyPatterns: [\"web/**\"]on the persona's own work directory — writes silently dropped on sync-back.model: \"claude-sonnet\"— bare alias without version, harness errors at spawn.Changes
New file
personas/persona-maker.md— the persona's full operating spec, including dedicated sections for Relayfile mount policy (allow-list idiom, the non-obvious!webvs!web/walker bug,readonlyPatternsscope rule, per-agent dotfile overlay,.gitsandbox behavior), MCP servers (two spec variants,\$VARsecret substitution, claude/codex/opencode support matrix,permissions.allowpairing), and Persona sidecar fields (path-vs-inline distinction with explicit "dry-run does NOT catch this" callout).persona-maker.json:
agentsMdContentwithagentsMd: \"./persona-maker.md\"(path form). The catalog generator atpackages/workload-router/scripts/generate-personas.mjsinlines the .md content into the published spec at build time, so the package still ships a single bundled JSON.claude-sonnet-4-6notclaude-sonnet).!dir(no slash) rule.Regenerated
packages/workload-router/src/generated/personas.ts.agentsMdContentis now 25,371 chars and contains all three sections, ready to ship.Design history
Earlier iterations tried two paths that don't survive cross-repo invocation:
agentsMdContent(one giant escaped string): worked but unmaintainable.personas/skills/*.mdfiles referenced vialocal/<name>source paths (the proactive-agents pattern): worked from inside the workforce repo, failed everywhere else. Local skill sources resolve relative paths againstprocess.cwd()at install time; the.mdfiles don't exist in user repos, socpfails. Reproduced from/tmp/:✗ 3 of 4 skill(s) failed.The proactive-agents pattern works because both the persona AND the skill files are co-located in the user's own repo. Persona-maker is a built-in shipped via npm — same pattern doesn't carry.
The
agentsMdsidecar approach gets the maintainability win (editable .md file with proper markdown structure) without the cross-repo failure: the generator already inlines the sidecar at build time and the harness loadsAGENTS.mdfrom the session cwd, with no runtime filesystem lookups against unfamiliar directories.Test plan
node -e \"require('./personas/persona-maker.json')\"parses;agentsMdresolved to./persona-maker.md.agentsMdContentnow 25,371 chars with## Relayfile mount policy,## MCP servers,## Persona sidecar fields./tmp/(non-workforce cwd) — the case that previously failed:✓ dry-run ok: 1 skill(s) installed cleanly.To test locally after merge
The published
agentworkforce@3.0.3on PATH won't pick this up until the next release. To test now:```bash
cd ~/Projects/AgentWorkforce/workforce
git pull
corepack pnpm install
corepack pnpm --filter @agentworkforce/workload-router --filter @agentworkforce/cli build
From any directory:
node ~/Projects/AgentWorkforce/workforce/packages/cli/dist/cli.js agent persona-maker
```
🤖 Generated with Claude Code