truecast

The expert teammates Claude Code doesn't ship with.

Install portable, versioned expert personas — a product manager, an architect, a security reviewer — into any project, run them in Claude Code, and keep your own customizations when the author improves them.

Status: working end-to-end — install · update · list · remove · doctor · prompt · publish, with a per-persona ownership ledger, atomic updates, and a sandboxed git/GitHub fetch. The same four verbs run from inside a Claude Code session as /truecast:install and friends, no terminal. Verified driving real Claude Code sessions (as a subagent and as a standalone agent); publish generates a Claude Code plugin marketplace (validated with claude plugin validate). Pre-1.0; the self-improving loop is next.

A persona is a small, greppable corpus + an identity, split into two owners:

• core/ — the provider's craft: agent.md (identity) + skills/ + knowledge/, indexed by persona.toml. Read-only; one global copy; you adopt updates deliberately.
• instance/ — your per-project job (mandate.md) + accumulated notes (work.md). Yours, committed in your repo, never touched by an update.

A bundled example: personas/product-manager/.

You could paste "act like a security expert" into your prompt. Two reasons not to:

• Its own context window. Each persona runs as a native Claude Code subagent — Anthropic's own mechanism — so its deep work happens off your main thread and returns one distilled result instead of flooding your conversation. Anthropic's research team puts it plainly: "Each subagent might explore extensively, using tens of thousands of tokens or more, but returns only a condensed, distilled summary of its work" (context engineering).
• Structured craft it reads on the job, not a costume. A persona is a versioned corpus of skills the agent Reads when a task matches — not vibes baked into a one-off prompt. You adopt the author's improvements deliberately, and your per-project customizations survive the update.

Two lines to set truecast up, one line per teammate — no terminal:

/plugin marketplace add wastedcode/truecast
/plugin install truecast@truecast
/truecast:install product-manager

Now @product-manager answers to that bare name, in this project and every other one. The truecast@truecast line installs the installer — the plugin that provides /truecast:install, /truecast:update, /truecast:list, and /truecast:remove. You type it once, ever. Swap product-manager for any of the eleven official personas: product-researcher, vc-seed, software-engineer, software-architect, security-engineer, qa, infrastructure, product-marketer, ui-ux-designer, sales.

Before it writes anything, /truecast:install shows you the plan — the version, the tools that teammate gets, and every path it will touch — and waits for a yes. It never overwrites a file truecast didn't write, and it copies from the marketplace clone already on your disk. First run only: if /truecast:install isn't recognized yet, /reload-plugins; if @<name> isn't, restart Claude Code once.

Updates come through the marketplace: /plugin marketplace update truecast, then /truecast:update <name> (or --all). Details in docs/managing-personas.md.

The first time you run a teammate with no job set, it asks what the project needs and writes its own mandate.md. Want installs from any git URL, doctor, prompt, and an ownership ledger? Use the truecast CLI below — same on-disk copy, so the two lanes can update each other's installs.

npm install -g @wastedcode/truecast    # installs the `truecast` command
truecast --help

Or from source:

git clone https://github.com/wastedcode/truecast && cd truecast
pnpm install && pnpm build
npm link                                   # puts `truecast` on your PATH

Requires Node ≥ 22. Pre-1.0: the CLI and the programmatic API may change between 0.x minors — see docs → Stability.

/truecast:install above covers the common case. The CLI adds installs from any git URL, an ownership ledger, plus doctor and prompt. It needs Node and a restart.

cd your-project
truecast install <git-url-or-path>[@version][#subpath]

# examples
truecast install https://github.com/wastedcode/truecast#personas/product-manager   # an official persona
truecast install ./personas/product-manager                       # local path
truecast install https://github.com/you/persona@1.2.0             # a GitHub release tag
truecast install https://github.com/you/monorepo#personas/pm      # a persona in a sub-directory

The eleven official personas (product-manager, product-researcher, vc-seed, software-engineer, software-architect, security-engineer, qa, infrastructure, product-marketer, ui-ux-designer, sales) live in this repo under personas/ — install any with …/truecast#personas/<name>. Then write the persona's job for this project in .truecast/agents/<name>/instance/mandate.md.

However you install it, a persona runs as a native Claude Code subagent. Its body carries an index of the persona's skills (each with a one-line summary and the path to Read), so the persona pulls the right skill on demand. Verified: given an open-ended task it Reads the matching SKILL.md files itself, then applies them. (/truecast:install and the CLI both materialize the subagent at ~/.claude/agents/<name>.md; the CLI additionally symlinks the craft into your project.)

After a CLI install, restart Claude Code, then bring the teammate into a normal session:

> have the product-manager pressure-test this idea: an AI that auto-prioritizes my to-dos

Claude delegates to the subagent (it's listed under /agents, and you can @agent-product-manager it explicitly). The subagent runs with the tools the persona declares (tools in its persona.toml), reads its mandate.md for the project job, and Reads the skills it needs.

Run a full claude session that is the persona — its whole craft loaded as the system prompt. truecast prompt emits that composed prompt; pipe it into claude:

cd your-project   # the project where you ran `truecast install`
claude --append-system-prompt "$(truecast prompt product-manager)" \
       --allowed-tools Read Grep WebSearch WebFetch \
       --model opus

Now the whole session thinks like the persona. --allowed-tools restricts it to the tools the persona declares (a main agent otherwise has the full toolset); --model matches its modelHint. (truecast prompt <name> just prints the system prompt — --append-system-prompt-file <file> works too.)

truecast runs one curated catalog, the marketplace this repo publishes, so a user adds it once and installs everything as <name>@truecast. To get your persona in, open a PR here with your personas/<name>/core/ (the source: agent.md, skills/, knowledge/, persona.toml). You don't generate plugin files or run publish; a maintainer publishes it into the catalog when your PR lands. Start from docs/authoring-personas.md and CONTRIBUTING.md.

Put a teammate in a project so everyone working in it gets the same one, with nothing to install by hand. Add this to the repo's .claude/settings.json and commit it:

{
  "extraKnownMarketplaces": {
    "truecast": { "source": { "source": "github", "repo": "wastedcode/truecast" } }
  },
  "enabledPlugins": ["product-manager@truecast"]
}

When someone opens the repo in Claude Code and trusts the folder, Claude Code offers to install the teammate for them. The expert travels with the code, not with each person's setup. Note the name: a persona installed this way is namespaced by its plugin, so it answers to product-manager:product-manager rather than a bare @product-manager — that's the price of portability, and it's why /truecast:install exists for the per-machine case. Only commit this for a marketplace you control, and review what a marketplace ships before you trust a folder.

truecast list [--check] [--project]   # what's installed; running vs latest; what's attached here
truecast update [<name>] [--dry-run]  # adopt newer craft; classified (patch/minor/major); your instance untouched
truecast remove <name> [--global]     # detach from this project (keeps instance/), or purge globally
truecast doctor [--fix]               # inspect + repair (drift, dangling pointer, stale artifacts)

See docs/managing-personas.md for the full model (consent, drift/--force, the discriminated update outcomes).

install resolves the project (the nearest enclosing git repo, or --project <path>), fetches the persona into a global cache (~/.truecast/personas/<name>/), symlinks the craft into the project, scaffolds your editable instance/, and materializes the subagent at ~/.claude/agents/<name>.md — whose body indexes the skills/knowledge for the persona to Read on demand (skills are not copied as global slash- commands; they're the persona's private craft). Every file truecast writes is tracked in a per-persona ledger (owned.json), under a per-persona lock, so concurrent installs never collide and truecast never clobbers a file it doesn't own.

publish is the parallel path. Instead of materializing into ~/.claude, it generates the committed plugin and marketplace files that Claude Code installs from.

docs/ — install, managing personas, authoring personas, and a shipped-vs-planned status table. (Kept in step with the code: a feature isn't done until it's documented.)

pnpm install
pnpm typecheck && pnpm test && pnpm lint && pnpm build

Requires Node ≥ 22 and pnpm. License: MIT. Design notes live in internal/ (git-ignored).