--- name: dispatch-as-project-agent description: Spawn a generic Agent wearing a project-specific agent's discipline (workaround for v0.1 runtime not discovering project agents) allowed-tools: Read Agent SendMessage argument-hint: " " mode: [orchestrate] --- # Dispatch As Project Agent ## Purpose In Claude Code, project-level agents at `/.claude/agents/.md` are NOT natively discoverable as `subagent_type` values by the Agent tool. The Agent tool only resolves the runtime built-ins (`general-purpose`, `Explore`, `Plan`, `claude-code-guide`, `statusline-setup`). This is a Claude Code limitation, not a YakOS one (incident:v0.2.0). **v0.3.0+: yakos start solves this for whole sessions.** Launching via `yakos start ` composes a `--agents` JSON object from both framework + project agent files and passes it on the claude command line — project agents become addressable as `subagent_type` for the session's lifetime. If you started the session with `yakos start`, you do NOT need this skill for the common case. **v0.4.2+: yakos dispatch covers cross-runtime + non-yakos-start sessions.** When the lead needs to dispatch a project agent in a session that wasn't launched via `yakos start` (e.g. a bare `claude` session), or wants to route the specialist to a different runtime (codex / gemini) than the lead, run from a Bash tool: yakos dispatch "" This shells out to the right runtime CLI per the agent's frontmatter `runtime:` field, runs the agent non-interactively, and returns the captured output. Audit trail at `~/.yakos-state/dispatch-log.ndjson`. **This skill (the inline-injection technique) is still useful** for two cases: 1. Read-only diagnosis tasks that should run inside the lead's context (cheaper than spawning a new process). 2. Quick one-offs where the agent body is small enough to copy into the prompt and the dispatch latency of `yakos dispatch` isn't worth the round-trip. For multi-file write tasks, prefer `yakos dispatch` — it gives each specialist a fresh context window and a clean exit. ## Scope Dispatch with project-agent discipline applied. Three orthogonal choices the lead makes per call: - **Spawn type**: `general-purpose` for write work; `Explore` for read-only diagnosis (cheaper, no Edit/Write/Bash). - **Discipline source**: project agent body alone, or project agent body + `extends:` framework template (preferred when `extends:` is declared). - **Task scope**: a single domain (backend / frontend / mobile / db / etc.). Cross-domain work stays with the lead, who dispatches each domain separately and synthesizes. ## When to use - The lead needs to dispatch a multi-file write task to a domain specialist (backend / frontend / mobile / database / etc.) AND wants the specialist's discipline (boundaries, anti-patterns, deferred-phase awareness) applied to the work. - The lead is operating in a session that has the project's `.claude/agents/` available as files (either rooted in the project or via `--add-dir`). ## When NOT to use - For read-only research tasks — `Explore` is cheaper and good enough; the inject-pattern's overhead isn't justified. - For work that fits inside the lead's own context — the lead has read all the agent bodies during familiarization; wearing the hat directly is fine for one-off work. - For tasks requiring `TeamCreate`-tied hooks (`team-lifecycle.sh`, `task-complete-dispatch.sh`). Those hooks fire on TeamCreate / TaskCompleted events; spawning via `general-purpose` skips the team primitives. ## Automated pass 1. **Read the project agent body.** Path is `/.claude/agents/.md`. 2. **Resolve `extends:` if present.** If frontmatter declares `extends: `, also read the framework template at `/lib/agents/.md`. The combined content is the discipline the spawned agent should apply. 3. **Compose the prompt.** Concatenate, in order: - A one-line preamble: "You are operating as the project's `` specialist. Apply the discipline in the agent body below." - The framework template body (if `extends:` was set). - The project agent body. - The actual task description (file:line, target outcome, boundaries). 4. **Spawn via `Agent`.** Use `subagent_type: "general-purpose"` so the spawned agent has full tool access (Edit, Write, Bash, etc.) needed for write work. For read-only diagnosis, `Explore` is the cheaper alternative. ## Manual pass The lead does what the runtime would otherwise do for a native dispatch: 1. **Verify the diff.** The spawned agent's summary describes intent; verify the actual diff before reporting work as done. The path-allowlist hook doesn't fire on `general-purpose` spawns — the lead is the path safety net. 2. **Run per-domain validators manually.** `task-complete-dispatch.sh` validators (`backend-validate.sh`, `frontend-validate.sh`, `db-migration-validate.sh`, etc.) don't fire on injected dispatch. Run them yourself against the touched files before approving. 3. **Surface peer messages to `decisions.md`.** Without team-routed mailboxes, any decision the spawned agent reaches must be mirrored into the project's running decisions doc by the lead. ## What the spawned agent loses (vs native dispatch) - **Hook coverage.** `team-lifecycle.sh`, `task-complete-dispatch.sh`, per-domain validators don't fire because the spawn isn't a TeamCreate member. The lead must run validators manually after the spawn returns. - **TaskList integration.** The spawned agent doesn't share the `~/.claude/tasks//` task list. The lead tracks tasks externally (TodoWrite is the in-session substitute). - **Mailbox / SendMessage routing.** Spawned agents can SendMessage to the lead, but peer-to-peer mailbox routing only works inside a team. Cross-spawn coordination goes through the lead. - **`agent_type` discriminator in stdin.** Phase 1.7's lead-vs-teammate discriminator (`agent_type` absent for lead-driven) doesn't apply — every spawned `general-purpose` agent looks the same to hooks. ## Example dispatch (PandaOS) The lead has a task: implement `POST /api/v1/clients/:id/meal-plans`. The owning specialist per CLAUDE.md is the backend (Go/Echo). 1. Read `/Users/tw/github/panda-os3.0/.claude/agents/backend.md`. 2. `extends: backend` → also read `/Users/tw/github/yakos/lib/agents/backend.md`. 3. Compose prompt: preamble + framework backend body + project backend body + task spec (the OpenAPI annotation, the audit-log requirement, the contract handoff to frontend). 4. `Agent({subagent_type: "general-purpose", description: "Backend: implement /meal-plans POST", prompt: })`. 5. On return, the lead runs `go build ./... && go vet ./... && go test ./...` and `grep -c writeAuditLog api/internal/service/meal_plan_service.go` before approving. ## Known gotchas - **Project agent not found.** The path was wrong (project not `--add-dir`'d, or filename mismatch). Surface the error; don't dispatch with partial discipline. - **`extends:` parent not found.** The framework template was renamed or removed. Read what's available and proceed with a comment that inheritance broke; update the project agent's `extends:` field separately. - **Composed prompt > context budget.** A particularly thick agent body + task description can exceed budget. Trim the task description; keep the agent body intact (the discipline is the point). ## Related - [`docs/team-shapes.md`](../../docs/team-shapes.md) — when to use which team composition; references this skill for the runtime dispatch path in v0.1. - [`lib/agents/lead-template.md`](../../lib/agents/lead-template.md) — the lead's role; this skill is one of the lead's tools. - Phase 8 finding (in panda-os3.0 `memory/session_checkpoint.md`) — the discovery that motivated this skill.