Apx Agency Agents

---
name: apx-agency-agents
description: Reusable agent templates from the vault — "una plantilla de agente", "agentes reutilizables", dev, marketing, ops, qa and support archetypes. Spawn a specialist, list, import into a project, create, or hide/restore a bundled default. Triggers: 'spawn agent', 'use Cody/Rocky/Tessa', 'list agents', 'agent vault', 'import agent', 'new agent'.
---

# apx-agency-agents — the APX agent vault

Global, project-agnostic library of agent templates. Two layers, deduped per-slug, user wins:

| Layer | Where | Mutability |
|---|---|---|
| **Bundled** | `<repo>/src/core/assets/agent-vault-defaults/<slug>.md` | Read-only. Visible unless tombstoned. |
| **User** | `~/.apx/agents/<slug>.md` | Read-write. Overrides bundled with same slug. |
| **Tombstones** | `~/.apx/agents/.removed.json` | Bundled slugs the user hid. |

Listing returns `bundled ∪ user`, with `source: "bundled" | "user" | "user-override"`. Editing a bundled entry is **copy-on-write** (materializes into user layer on save). Deleting bundled **tombstones** (restorable); deleting user-only removes the file.

## Bundled starter pack (14 templates)

### Named team (from acme-apps)

| Slug | Role | Strength |
|---|---|---|
| `orchestrator` | Pipeline orchestrator | Autonomous task routing, multi-agent coordination |
| `architect` | Software architect | System design, tradeoffs, ADRs |
| `developer` | Senior Laravel dev | Code, refactors, technical leadership |
| `qa-engineer` | QA / beta tester | Reality checks, test plans, real-user empathy |
| `growth` | Growth hacker | Content, campaigns, SEO, copy |
| `security` | Security specialist | Audits, threat models, hardening |
| `pm` | Senior PM | Tasklists, roadmaps, stakeholder comms |
| `designer` | UI/UX reviewer | Visual audits, usability (uses browser-use) |
| `billing` | Billing / commercial ops | Stripe, invoicing, plan logic |

### Generic specialists (from PandaProject)

`development`, `marketing`, `ops`, `qa`, `support` — plain functional roles without a persona.

Bundled templates ship with `language: es` and **no `model:`** — they inherit the project/global default. Set a model on import or by editing the vault file.

## Commands

```bash
# List (bundled + overrides, tagged [bundled]/[user]/[override])
apx agent vault list
apx agent vault list --all              # include tombstoned

# Create (writes ~/.apx/agents/<slug>.md)
apx agent vault add reviewer \
  --role "Code reviewer" \
  --model ollama:llama3.2:3b \
  --language es \
  --skills code-review,git \
  --description "Reviews PRs and pushes back on hand-wavy diffs."

# Delete: user-only → physical delete; bundled → tombstone
apx agent vault rm qa-engineer
apx agent vault restore qa-engineer        # un-tombstone

# Import into current project
apx agent import developer
apx agent import qa-engineer --copy        # copy into .apc/agents/ for local edits
apx agent import orchestrator --force

# Daemon tool API equivalents:
list_vault_agents()
import_agent({ slug: "cody-developer", project: "<name-or-path>" })
```

## Web equivalents

Agent defaults tab (`/p/0/agent-defaults`): same CRUD — "New" (POST `/api/agents/vault`), per-card "Edit" (PATCH `/api/agents/vault/:slug`, copy-on-write for bundled), "Delete"/"Hide" (DELETE), "Show removed" toggle with "Restore" button.

## Which agent to use

- User says **"spawn/use Cody/Rocky/Tessa/Max/Arch/Sid/Vera/Roby/Finn"** → import that exact slug from named team.
- User wants **"developer"/"QA"/"marketing" without a persona** → use generics (`development`, `qa`, `marketing`, …).
- **Not in vault** → `apx agent vault add <slug>` for a new template, or `apx agent add <slug> --prompt -` directly in a project for a one-off. A new agent needs its system prompt (the file body), not just `--role`/`--description` — see `apx-agent`.
- **Fresh install** → bundled defaults are always present (no sync step); appear in `apx agent vault list` immediately.

## File locations

```
<APX repo>/src/core/assets/agent-vault-defaults/<slug>.md   ← canonical bundle (committed)
~/.apx/agents/<slug>.md                            ← user vault (sync target)
<project>/.apc/agents/<slug>.md                    ← project-local copy (after import --copy)
```

Vault format = project agent format:

```
---
role: <human-readable role>
model: <provider:model>
description: <short description shown in UI grid>
language: es
skills: a, b, c
tools: x, y
is_master: false
---

<markdown body — system prompt extension>
```

## Frontmatter fields the runtime reads

| Field | Effect |
|---|---|
| `role` | Shown in CLI/web; appears as "Role: …" in prompt. |
| `model` | Default model for engine routing. |
| `description` | Shown in `/api/agents/vault` and AgentDefaultsTab cards. |
| `language` | Adds "Default language: <code>" to system prompt. |
| `skills` | Per-agent skill names; bodies loaded by skill resolution. |
| `tools` | Allowlist that *narrows* the agent's callable tools. Catalog names (`glob`, `memory_get`, `run_command`) map to native handlers. **Empty → broad default: the whole registry minus a few host-only tools** (`set_identity`, `set_permission_mode`, `add_project`, `import_agent`). Declaring the field takes tools away, so list everything the agent needs. |
| `is_master` | If true, marked master in project (badge + ordering). |

## Related skills

- **[apx-agent](../apx-agent/SKILL.md)** — per-project agent CRUD. Vault = library; this = workshop.
- **[apx-runtime](../apx-runtime/SKILL.md)** — delegating to external coding CLIs from inside an agent.

## Gotchas

- **Bundled defaults are always present** — no sync step. Removing tombstones; editing copies to user layer.
- The templates are named after ROLES, not personas: `orchestrator`, `pm`, `developer`. The persona is assigned when the agent is installed, from the shared name pool, so a project never ends up with an agent whose name shadows the super-agent's own.
- The `agency-agents` skill in `~/.claude/skills/` pulls from `msitarzewski/agency-agents` on GitHub. APX bundles a snapshot in `src/core/assets/agent-vault-defaults/` so installs are offline-first. To refresh upstream, edit the bundle and re-commit; user overrides are untouched.