{"slug": "structured-subagents-for-claude-code", "title": "Structured Subagents for Claude Code", "summary": "WastedCode released TrueCast, a CLI and plugin system that installs portable expert personas—such as product manager, architect, and security reviewer—into Claude Code sessions. The tool provides versioned, sandboxed subagents with an ownership ledger that preserves user customizations during updates, and includes eleven official personas for various roles. TrueCast is pre-1.0 and requires Node ≥ 20.", "body_md": "The expert teammates Claude Code doesn't ship with.\n\nInstall portable, versioned **expert personas** — a product manager, an architect, a security reviewer\n— into any project, run them in Claude Code, and keep your own customizations when the author improves\nthem.\n\n**Status:** working end-to-end — `install`\n\n· `update`\n\n· `list`\n\n· `remove`\n\n· `doctor`\n\n· `prompt`\n\n· `publish`\n\n,\nwith a per-persona ownership ledger, atomic updates, and a sandboxed git/GitHub fetch. Verified driving real\nClaude Code sessions (as a subagent and as a standalone agent); `publish`\n\ngenerates a Claude Code plugin\nmarketplace (validated with `claude plugin validate`\n\n). Pre-1.0; the self-improving loop is next.\n\nA persona is a small, greppable corpus + an identity, split into two owners:\n\n— the provider's craft:`core/`\n\n`agent.md`\n\n(identity) +`skills/`\n\n+`knowledge/`\n\n, indexed by`persona.toml`\n\n. Read-only; one global copy; you adopt updates deliberately.— your per-project job (`instance/`\n\n`mandate.md`\n\n) + accumulated notes (`work.md`\n\n). Yours, committed in your repo,**never touched by an update.**\n\nA bundled example: [ personas/product-manager/](/wastedcode/truecast/blob/main/personas/product-manager).\n\nInstall straight into a live Claude Code session:\n\n```\n/plugin marketplace add wastedcode/truecast\n/plugin install product-manager@truecast\n/reload-plugins\n```\n\nNow talk to the teammate by name. You only type `@truecast`\n\nat install; it's the marketplace the plugin\ncomes from, like an npm scope. Swap `product-manager`\n\nfor any of the eleven official personas:\n`product-researcher`\n\n, `vc-seed`\n\n, `software-engineer`\n\n, `software-architect`\n\n, `security-engineer`\n\n, `qa`\n\n,\n`infrastructure`\n\n, `product-marketer`\n\n, `ui-ux-designer`\n\n, `sales`\n\n.\n\nThe first time you run a plugin teammate with no job set, it asks what the project needs and writes its own\n`mandate.md`\n\n. Want a global, versioned copy you update on your terms, with an ownership ledger that keeps\nyour edits when the author ships changes? Use the `truecast`\n\nCLI below.\n\n```\nnpm install -g @wastedcode/truecast    # installs the `truecast` command\ntruecast --help\n```\n\nOr from source:\n\n```\ngit clone https://github.com/wastedcode/truecast && cd truecast\npnpm install && pnpm build\nnpm link                                   # puts `truecast` on your PATH\n```\n\nRequires Node ≥ 20. **Pre-1.0:** the CLI and the programmatic API may change between `0.x`\n\nminors — see\n[docs → Stability](/wastedcode/truecast/blob/main/docs/README.md#stability-pre-10).\n\nThe plugin path above is the fast lane. The CLI is the control lane: a global, versioned copy you update deliberately, with a per-persona ownership ledger so your customizations survive an update.\n\n```\ncd your-project\ntruecast install <git-url-or-path>[@version][#subpath]\n\n# examples\ntruecast install https://github.com/wastedcode/truecast#personas/product-manager   # an official persona\ntruecast install ./personas/product-manager                       # local path\ntruecast install https://github.com/you/persona@1.2.0             # a GitHub release tag\ntruecast install https://github.com/you/monorepo#personas/pm      # a persona in a sub-directory\n```\n\nThe eleven official personas (`product-manager`\n\n, `product-researcher`\n\n, `vc-seed`\n\n, `software-engineer`\n\n,\n`software-architect`\n\n, `security-engineer`\n\n, `qa`\n\n, `infrastructure`\n\n, `product-marketer`\n\n, `ui-ux-designer`\n\n,\n`sales`\n\n) live in this repo under [ personas/](/wastedcode/truecast/blob/main/personas) — install any with\n\n`…/truecast#personas/<name>`\n\n.\nThen write the persona's job for this project in `.truecast/agents/<name>/instance/mandate.md`\n\n.A CLI install generates a native Claude Code **subagent** at `~/.claude/agents/<name>.md`\n\nand symlinks the\ncraft into your project. Its body carries an **index of the persona's skills** (each with a one-line\nsummary and the path to Read), so the persona pulls the right skill on demand. Verified: given an\nopen-ended task it Reads the matching `SKILL.md`\n\nfiles itself, then applies them. (A plugin install ships\nthe same body; only the delivery differs.)\n\nRestart Claude Code after a CLI install (the plugin path above needs no restart), then bring it into a normal session:\n\n```\n> have the product-manager pressure-test this idea: an AI that auto-prioritizes my to-dos\n```\n\nClaude delegates to the subagent (it's listed under `/agents`\n\n, and you can `@agent-product-manager`\n\nit\nexplicitly). The subagent runs with the tools the persona declares (`tools`\n\nin its `persona.toml`\n\n),\nreads its `mandate.md`\n\nfor the project job, and Reads the skills it needs.\n\nRun a full `claude`\n\nsession that *is* the persona — its whole craft loaded as the system prompt.\n`truecast prompt`\n\nemits that composed prompt; pipe it into `claude`\n\n:\n\n```\ncd your-project   # the project where you ran `truecast install`\nclaude --append-system-prompt \"$(truecast prompt product-manager)\" \\\n       --allowed-tools Read Grep WebSearch WebFetch \\\n       --model opus\n```\n\nNow the whole session thinks like the persona. `--allowed-tools`\n\nrestricts it to the tools the persona\ndeclares (a main agent otherwise has the full toolset); `--model`\n\nmatches its `modelHint`\n\n. (`truecast prompt <name>`\n\njust prints the system prompt — `--append-system-prompt-file <file>`\n\nworks too.)\n\n[claudemux](https://github.com/wastedcode/claudemux) runs real, login-backed `claude`\n\nsessions you drive\nby name and that tell you when a turn is *actually* done. Flags after `--`\n\nare forwarded straight to\n`claude`\n\n, so you launch a persona as a full standalone agent and talk to it over time:\n\n```\n# render the persona's prompt once\ntruecast prompt product-manager > /tmp/pm.md\n\n# spawn it as a full, persistent claude session (everything after `--` goes to claude)\nclaudemux spawn pm --cwd ./your-project --trust-workspace -- \\\n  --append-system-prompt-file /tmp/pm.md \\\n  --allowed-tools Read Grep WebSearch WebFetch --model opus\n\n# then drive it — one-shot, or send/wait/messages\nclaudemux ask pm \"We're thinking of building X next. Worth it?\"\n```\n\nEach persona is its own session, addressed by name — `tmux attach`\n\nto watch it work, or spin up a whole\nteam (`claudemux spawn architect … / spawn security …`\n\n) and coordinate them from one place. The CLI maps\n1:1 to a Node library if you'd rather drive it from code (`create({ name, cwd, extraArgs: [...] })`\n\n).\n\ntruecast runs **one curated catalog**, the marketplace this repo publishes, so a user adds it once and\ninstalls everything as `<name>@truecast`\n\n. To get your persona in, **open a PR here** with your\n`personas/<name>/core/`\n\n(the source: `agent.md`\n\n, `skills/`\n\n, `knowledge/`\n\n, `persona.toml`\n\n). You don't\ngenerate plugin files or run `publish`\n\n; a maintainer publishes it into the catalog when your PR lands.\nStart from [ docs/authoring-personas.md](/wastedcode/truecast/blob/main/docs/authoring-personas.md) and\n\n[.](/wastedcode/truecast/blob/main/CONTRIBUTING.md)\n\n`CONTRIBUTING.md`\n\nPut a teammate in a project so everyone working in it gets the same one, with nothing to install by hand.\nAdd this to the repo's `.claude/settings.json`\n\nand commit it:\n\n```\n{\n  \"extraKnownMarketplaces\": {\n    \"truecast\": { \"source\": { \"source\": \"github\", \"repo\": \"wastedcode/truecast\" } }\n  },\n  \"enabledPlugins\": [\"product-manager@truecast\"]\n}\n```\n\nWhen 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. Only commit this for a marketplace you control, and review what a marketplace ships before you trust a folder.\n\n```\ntruecast list [--check] [--project]   # what's installed; running vs latest; what's attached here\ntruecast update [<name>] [--dry-run]  # adopt newer craft; classified (patch/minor/major); your instance untouched\ntruecast remove <name> [--global]     # detach from this project (keeps instance/), or purge globally\ntruecast doctor [--fix]               # inspect + repair (drift, dangling pointer, stale artifacts)\n```\n\nSee [docs/managing-personas.md](/wastedcode/truecast/blob/main/docs/managing-personas.md) for the full model (consent, drift/`--force`\n\n,\nthe discriminated update outcomes).\n\n`install`\n\nresolves the project (the nearest enclosing git repo, or `--project <path>`\n\n), fetches the persona into a\nglobal cache (`~/.truecast/personas/<name>/`\n\n), symlinks the craft into the project, scaffolds your\neditable `instance/`\n\n, and materializes the subagent at `~/.claude/agents/<name>.md`\n\n— whose body indexes\nthe skills/knowledge for the persona to Read on demand (skills are **not** copied as global slash-\ncommands; they're the persona's private craft). Every file truecast writes is tracked in a **per-persona\nledger** (`owned.json`\n\n), under a per-persona lock, so concurrent installs never collide and truecast\nnever clobbers a file it doesn't own.\n\n`publish`\n\nis the parallel path. Instead of materializing into `~/.claude`\n\n, it generates the committed\nplugin and marketplace files that Claude Code installs from.\n\n[ docs/](/wastedcode/truecast/blob/main/docs) —\n\n[install](/wastedcode/truecast/blob/main/docs/install.md),\n\n[managing personas](/wastedcode/truecast/blob/main/docs/managing-personas.md),\n\n[authoring personas](/wastedcode/truecast/blob/main/docs/authoring-personas.md), and a shipped-vs-planned status table. (Kept in step with the code: a feature isn't done until it's documented.)\n\n```\npnpm install\npnpm typecheck && pnpm test && pnpm lint && pnpm build\n```\n\nRequires Node ≥ 20 and pnpm. License: MIT (intended). Design notes live in `internal/`\n\n(git-ignored).", "url": "https://wpnews.pro/news/structured-subagents-for-claude-code", "canonical_source": "https://github.com/wastedcode/truecast", "published_at": "2026-06-14 16:38:38+00:00", "updated_at": "2026-06-14 16:42:01.073075+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "large-language-models", "ai-agents"], "entities": ["WastedCode", "TrueCast", "Claude Code", "GitHub", "npm"], "alternates": {"html": "https://wpnews.pro/news/structured-subagents-for-claude-code", "markdown": "https://wpnews.pro/news/structured-subagents-for-claude-code.md", "text": "https://wpnews.pro/news/structured-subagents-for-claude-code.txt", "jsonld": "https://wpnews.pro/news/structured-subagents-for-claude-code.jsonld"}}