CLAUDE.md — agent-launcher domain

Guidance for working inside agent-launcher/. See the root CLAUDE.md for repo-wide rules.

What this domain is

A plugin that scaffolds and launches Claude Managed Agents (CMA) in the user's own Anthropic account, organized around a per-session goal that compiles into a loop or workflow. Inspired by anthropics/launch-your-agent (Apache-2.0); independent re-implementation, not a fork.

Non-negotiable rules (enforced by SPEC.md + validators)

1. Deterministic scaffolders only. Every script under skills/*/scripts/ is stdlib-only and makes no network/API calls. Live launches are emitted as BYOK curl. Do not add requests, anthropic, or any network client.
2. Never surface the API key. Launch scripts read $ANTHROPIC_API_KEY; no tool echoes/logs/writes a key. payload_validator.py and reviewers check this.
3. CMA limits are law. Keep references/cma-primitives.md as the source of truth for ceilings; validators must match it.
4. Bounded loops only. loop_compiler.py never emits a grade→iterate loop without a max_iterations cap (1..20).
5. The hook is opt-in and crash-proof. Gated by AGENT_LAUNCHER_SESSION=1; exits 0 on any error. Never make it fire unconditionally.
6. The folder is the user's. All artifacts go under ./my-agent/; scripts accept --out-dir and default there. Never write into the plugin folder.

Structure

• skills/agent-launcher-orchestrator/ — context: fork goal router (goal_router.py, goal_state.py, loop_compiler.py).
• skills/{interview,stage-launch,grade-iterate,run-without-you,wrap-up}/ — one phase each, 3 tools each.
• agents/ — cs-agent-launcher-orchestrator + 3 phase specialists.
• commands/ — 8 /cs:* commands.
• hooks/ — opt-in session_start.py / session_end.py + hooks.json.
• references/ — 5 shared docs. assets/ — schema + templates + example.

Tool conventions

• Every tool: argparse with real --help, a --sample that runs a deterministic demo and exits 0, and JSON output via --json where a machine reads it.
• Default output dir ./my-agent/; never assume network access.
• Import shared logic via relative sys.path insert (see how the orchestrator tools import goal_state).

Forcing-question discipline

Every SKILL.md ships a "Forcing-question library" (Matt Pocock grill-with-docs): walk one question at a time, recommend an answer, cite the reference. The /cs:grill-agent-launcher command surfaces them.

When editing

• Changing a CMA limit → update references/cma-primitives.md and every validator in lockstep.
• Adding a loop shape → update loop_compiler.py and references/loops-and-workflows.md.
• Keep SPEC.md authoritative; if you ship something different, record it in the delivery report.