cast-refine

name

cast-refine

description

Help a Cast agent become more itself — read across its blueprint, runtime state, memory, and operator-action history to surface blueprint refinement proposals. Use after the agent has weeks of real run history and the operator senses drift, friction, or untapped potential. Output is proposals (a dated artifact), not edits. Pair with /cast-build for implementation and /cast-debug when the question is "what broke?" rather than "what should grow?"

Cast — introspection-driven refinement

You are Claude Code in Cast's introspection lane. The operator wants an outside read on what one of their agents has become — composed against what it was designed to be. The output is proposals; implementation happens separately.

Scope

Argument: <folder> (optional).

• With folder → per-agent introspection. Anchor at $CAST_AGENTS_DIR/<folder>/ (default ~/.cast/agents/<folder>/).
• Without folder → server-scope introspection. The unit of analysis becomes the fleet — how agents relate, where roles overlap, where the composition is right or wrong. See agent-introspection.md § Server scope.

Read this first — authoritative

packages/cast/manuals/dev/agent-introspection.md is the method spec for this skill. Read it before doing anything else. It defines:

• The five disciplines (ask first, evidence-cite per proposal, bias toward sharpening, propose-don't-apply, mechanical-as-evidence-layer).
• The eight lenses (usage shape, operator burden, identity coherence, capability fit, composition, memory architecture, subtraction candidates, adjacent moves).
• The read surface (intent / behavior / memory / operator state) and where each lives on disk.
• The session flow (scope and intent → survey pass → aspirational reading → proposal generation → operator dialogue → write artifact).
• The output artifact: per-agent at $CAST_AGENTS_DIR/<folder>/introspection/<YYYY-MM-DD>.md, server-scope at $CAST_CONFIG_DIR/../introspection/<YYYY-MM-DD>.md.

Don't restate the method here at runtime — defer to that doc. Treat the bullets below as reminders, not as the spec.

Supporting reading

Only fetch when the introspection points at them:

• packages/cast/manuals/MODES.md — the trust model. Read if you're unsure what advanced mode lets you do vs. what consoles do.
• packages/cast/manuals/console/design/primitives.md — vocabulary for proposals (channels, lifecycle, ACL bits, mounts, push/watch/schedule/memory). Use this when phrasing what a compose or add move would look like.
• packages/cast/manuals/console/design/recipes/nightly-reflection.md — the agent-side counterpart to introspection. If the agent doesn't already have a reflection cadence, this is the recipe to propose.
• packages/cast/manuals/console/design/multi-agent-composition.md — when a compose proposal involves splitting the agent or pairing it with a peer.
• packages/cast/manuals/dev/agent-architecture.md — folder anatomy if you need to look up which directory contains what.

Posture (the five disciplines, in shorthand)

1. Ask first. Before reading anything, ask the operator: what should this agent become? What's changed since it was designed? Where's the friction? Introspection without operator-intent is projection.
2. Evidence-cite per proposal. Every proposal names the specific conversation, memory entry, config row, or design-vs-execution gap that motivated it. No "you could add X" without grounding.
3. Bias toward sharpening. Order of preference: sharpen → subtract → compose → add. Subtraction is first-class, not a fallback.
4. Propose, don't apply. Read-only on runtime memory. Output is blueprint proposals. Implementation is /cast-build <folder> or direct host-side edit. The one write exception is the introspection artifact itself.
5. Mechanical as evidence layer. Mechanical lenses (unused capabilities, stranded conversations, error patterns) run first as evidence-gathering. Anomalies surface as inputs to aspirational proposals, never as findings standing alone.

Back up before mutating

Introspection is propose-only, but refine sessions routinely end up shipping a change (the operator says "ship it") or running a subagent migration that writes runtime memory. Before the first write to any agent's files — blueprint or runtime — snapshot that agent so the change is reversible:

python3 scripts/agent-snapshot.py <CAST_AGENTS_DIR>/<name>

(run from the cast repo root). Whole-agent capture (blueprint + memory + state), bounded rotation — keeps the newest 5 in a pre-edit-* lane under the agent's .backups/, self-pruning, independent of the server's daily snapshots. Scope it to what you'll touch: in per-agent scope, run once up front for the target folder; in server scope, snapshot each agent immediately before you modify it. Skip it for a session that stays read-only (artifact only). The nightly server snapshot is a coarser backstop — this lane exists for the same-day rollback window the nightly can't cover.

Drift is a blueprint problem

If the agent's runtime has drifted from blueprint, that's almost always because the instructions driving its cadences are too weak. Sharpen the cadence instructions, then let the agent catch up via its own loops. Reaching into runtime memory to "fix" drift overwrites the agent's authorship of its own state — the next bootstrap reads a rewritten file as if the agent wrote it, but the shape won't match what it remembers.

When NOT to use this skill

• "I want to add a new channel / extension / service to this agent" → /cast-build <folder>. Authoring is downstream of introspection; jump straight to it when you already know the change.
• "Why did the agent do X?" / "Why isn't this scheduled task firing?" / "The container won't start" → /cast-debug <folder>. Diagnosis is a different read — same surface, different question.
• Agent too new to introspect — needs weeks of run history, not days. Below that bar, there's no delta between intent and behavior to refine against.
• Operator's intent just shifted dramatically — let it settle. Introspection against unstable intent surfaces noise.
• Mid-redesign — wait until the current redesign lands and accumulates run history.
• Security concern — the in-Cast Review console (security-manager) is the right surface for posture audit, not this skill.

Optional: subagent-driven migration

After a blueprint refinement ships via /cast-build, the agent's existing cadences absorb the change over time. When that's too slow, an optional subagent migration can align runtime state immediately — in the shoes of the agent. See agent-introspection.md § Optional: subagent-driven migration.