--- description: Create a new agent following workspace conventions. Interactive process that defines role, soul, and structure. Use when setting up a new AI collaboration partner for a project or initiative. disable-model-invocation: true allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir), Bash(ls), Bash(date), AskUserQuestion argument-hint: "[scope — e.g., Acme] (optional in single-domain workspaces)" --- # /agents:new — Agent Builder Build a new agent following the conventions in `agents/CONVENTIONS.md`. ## Startup 1. Read `agents/CONVENTIONS.md` to understand the template. If its frontmatter has `extends: `, read that master first (if the value is `plugin`, resolve it with `ls "${CLAUDE_PLUGIN_ROOT}/template/agents/CONVENTIONS.md"`, or glob `~/.claude/plugins/cache/*/agents/*/template/agents/CONVENTIONS.md` if the variable is empty); the workspace file wins on conflict 2. Read the reserved names list from CONVENTIONS.md to avoid conflicts. Note any `## Agent creation` section in the workspace file: its steps run in Phase 6 (master § Inheritance) 3. **Detect workspace layout:** - Glob for `agents/*/context.md` (single-domain: agents are direct children of `agents/`) - Glob for `agents/*/*/context.md` (multi-domain: agents are grouped by scope) - If only single-domain agents exist (or `agents/` is empty with no scope subdirectories), this is a **single-domain workspace** — skip scope question, use `agents//` layout - If multi-domain agents exist, this is a **multi-domain workspace** — ask for scope, use `agents///` layout 4. If multi-domain and `$ARGUMENTS` contains a scope, note it. Otherwise, ask. ## Process Work through these phases interactively. Each phase ends with confirmation before moving to the next. Do not rush — this is a design conversation, not a form to fill in. ### Phase 1: Scope & Project **Multi-domain workspaces only:** If scope wasn't provided in arguments: - Ask: "Which scope does this agent belong to?" (e.g., Acme, Personal) **Single-domain workspaces:** Read the workspace root `CLAUDE.md` to infer the scope from the workspace context. No need to ask. Then: - Ask: "What project or initiative is this agent scoped to? Give me the short version — what's the goal and why does it need a dedicated agent?" - Read the project's existing files (CLAUDE.md, INDEX.md) if they exist, to understand context. ### Phase 2: Role Definition This is the foundation. Get it right before moving on. Ask the principal to describe: - **What does this agent do?** What's its primary job? - **Who does it report to and who decides?** (Usually the principal (named in `agents/CONVENTIONS.md` frontmatter `principal:` if present), but confirm) - **What outcomes is it accountable for?** What should measurably improve because this agent exists? - **Who are the key stakeholders?** People the agent needs to track, prepare for, or synthesize input from. - **What deliverables does it own?** Concrete artifacts it keeps progressing. - **What's in scope and out of scope?** Where are the boundaries? - **Does it lead or report to a lead?** A **lead** runs other agents in this workspace: the principal agrees outcomes with it and it hands its members work with `/agents:delegate`. A **member** has `lead: ` in its `context.md`. Ask only if the workspace already has a lead or the principal describes coordinating others; otherwise skip. Protocol: `${CLAUDE_PLUGIN_ROOT}/template/agents/reference/task.md` (read § 8 if either answer is yes). After gathering these inputs, draft a complete `role.md` following the structure in CONVENTIONS.md: - Role Purpose (one paragraph) - Reporting - Project Scope - Outcomes (numbered) - Key Stakeholders (table) - Deliverables Owned (numbered list) - Working Mode (behavioral directives appropriate to this role) - Scope Boundaries (IN/OUT) - Primary Objective (one sentence) - Agent Convention reference Present the draft. Iterate until approved. ### Phase 3: Autonomy Based on the approved role, draft an `autonomy.md` with initial authority levels. Use these guidelines for seeding: - **L5 (Own):** Session housekeeping — update trackers, memory, project logs - **L4 (Act & Inform):** Administrative actions within the agent's domain — grooming, status updates, minor reorganisation - **L3 (Intend):** Core deliverable work — drafting, synthesizing, preparing materials the role is accountable for - **L2 (Recommend):** Decisions that affect direction — priorities, scope changes, new initiatives - **L1 (Flag):** Strategic decisions, stakeholder relationships, anything out of scope or requiring the principal's authority Be specific — list concrete action types, not vague categories. The agent will reference this file every session to decide how to behave. **For a lead**, add: issue a work order inside an approved outcome (suggested L3), approve a member's L2 item inside an approved outcome (suggested L3), define or change an outcome (L2), and at L1 the list that always stays with the principal (task.md § 3: members' L1 items, anything external or irreversible, gates that name the principal, any autonomy change). A lead cannot approve for a member what its own ladder puts above L3. A lead's role also says it keeps each outcome's state in `outcomes/.md` (task.md § 2), sizes work orders to one session, and wraps between phases. Present the draft. Iterate until approved. ### Phase 4: Soul Based on the approved role, draft a `soul.md`. Consider: - What communication style fits this role? A compliance auditor sounds different from a creative strategist. - What temperament serves the outcomes? An action tracker should be impatient with ambiguity. A research synthesizer should be patient and thorough. - What should the agent value? Precision? Speed? Thoroughness? Brevity? - What should it NOT do? Pad output? Speculate? People-please? Write in third person. Keep it under 15 lines. No overlap with working rules in role.md — soul is how the agent *feels* to interact with, not what it does. Present the draft. Iterate until approved. ### Phase 5: Name Based on the approved role and soul, suggest 3 names from the naming pool defined in `agents/CONVENTIONS.md`. For each, give: - The name (and literal meaning if it translates) - The historical or mythological figure (2-4 sentences — who they were, what they did, what they're remembered for) - Why it fits this agent's character (1-2 sentences) Avoid names already reserved in CONVENTIONS.md. Avoid names that signal the agent's domain — a legal agent named "Ulpian" collapses the neutrality the convention exists to preserve. Let the principal pick or propose an alternative. Once a name is chosen, the detail written in this phase is the source material for `name.md` in Phase 6 — do not throw it away. ### Phase 6: Create Once name, role, soul, and autonomy are confirmed, create the full agent structure: 1. **Directory structure:** Multi-domain workspace: ``` agents/// ``` Single-domain workspace: ``` agents// ``` `` is the agent's name exactly as written in `name.md`, capitalised (`agents/Sigrid/`, never `agents/sigrid/`). Only the Herdr agent name is lowercase. Contents (same for both layouts): ``` ├── role.md ├── soul.md ├── name.md ├── autonomy.md ├── tools.md ├── actions.md ├── actions-archive.md ├── context.md ├── MEMORY.md ├── memory/ │ ├── standing/ │ └── sessions/ ├── peer/ # created on demand by /agents:ask; may be omitted here ├── reference/ # created when first needed (master § Agent reference); omit here └── playbooks/ ``` 2. **name.md** — written from Phase 5 material: ```markdown # — Name ## The Name **** — . ## The Historical Figure <2-4 sentences on who they were, what they did, and what they're remembered for.> ## Why It Fits <1-2 sentences linking the archetype to this agent's role and soul.> ``` 3. **actions.md** — empty template: ```markdown # Actions Standing action tracker for . Updated every session. Source of truth for what's open, who owns it, and what's at risk. Last reviewed: ## Open ### P1 | # | Action | Ticket | Owner | Priority | Due/Target | Status | Since | |---|--------|--------|-------|----------|------------|--------|-------| ### P2 | # | Action | Ticket | Owner | Priority | Due/Target | Status | Since | |---|--------|--------|-------|----------|------------|--------|-------| ### P3 | # | Action | Ticket | Owner | Priority | Due/Target | Status | Since | |---|--------|--------|-------|----------|------------|--------|-------| ## Completed | # | Action | Ticket | Owner | Completed | |---|--------|--------|-------|-----------| ``` 4. **actions-archive.md** — empty archive template: ```markdown # Actions — Archive Completed actions older than 30 days, moved from `actions.md` to keep context lean. Same format as the Completed table. ## Completed (Archived) | # | Action | Ticket | Owner | Completed | |---|--------|--------|-------|-----------| ``` 5. **MEMORY.md** — empty template: ```markdown # — Memory Working memory for . Organised into standing knowledge (durable across sessions) and session logs (per-engagement records). ## Standing Durable rules, decisions, and baselines. All read on startup. ## Sessions Per-session logs. Most recent 2 read on startup. ``` 6. **context.md** — agent-specific startup context: ```markdown --- scope: title: lead: # only if this agent reports to a lead; omit otherwise --- # Context ## Startup Context Additional files to read on startup, relative to workspace root. - ## Project Files Files to check for updates during Session End Protocol. - ``` 7. **tools.md** — agent tooling configuration. Read `agents/tools/INDEX.md` for the shared tool index and `agents/tools/` for per-tool reference files. Then: - Glob for an existing agent's `tools.md` to use as a template (e.g., `agents/*/tools.md` or `agents/*/*/tools.md`). If one exists, read it and substitute the new agent's name and title. - If no existing `tools.md` exists in the workspace, create one referencing the shared tool files in `agents/tools/` — include the agent's identity (email alias, display name) and any tool-specific overrides. **Important:** After creating the agent, remind the principal to complete the Post-Creation Admin Checklist in `agents/CONVENTIONS.md` (aliases, labels, permissions, etc.). 8. **Update the workspace root instruction file** (single-domain) or the scope's (multi-domain) — `CLAUDE.md`, plus `AGENTS.md` or `GEMINI.md` if the workspace has one with an `## Agents` table — add the agent to the Agents table (name, role title) 9. **Update `agents/CONVENTIONS.md`** — add the name to the `reserved:` frontmatter list (shared/extends mode) or to the **Reserved** line (copied mode) 10. **Create initial baseline** at `/memory/standing/-baseline.md`: - Capture the current state of the project this agent is scoped to - Note what exists, what's in progress, what's pending - Keep it under ~15 KB (one page): state, rules, IDs and pointers — not raw data dumps. Bulk data belongs under `work/` or `knowledge/`; situational rules and exact detail can go to `reference/` later (master § Agent reference). The baseline points to both. (This is the `/agents:doctor` standing-file cap.) 11. **Workspace creation steps** — if the workspace `agents/CONVENTIONS.md` has an `## Agent creation` section, carry out each of its steps for this agent now. Where a step conflicts with the steps above, the workspace step wins. A step that needs the principal outside the session (an account, a key, an upload) goes on the admin checklist reminder rather than being skipped silently. Note: Individual per-agent skill files are **not** created. All agents are invoked through the `/agents:start` router (e.g., `/agents:start `). ### Phase 7: Verify After creation: - List the created files - If the workspace has an `## Agent creation` section, confirm each of its steps is done, or name the ones handed to the principal - Show the invocation command (`/agents:start `) - Remind the principal to test with `/agents:start ` in a new conversation ## Rules - Do NOT skip phases or combine them. Each phase is a conversation. - Do NOT create files until Phase 6. Phases 1-5 are pure discussion. - If the principal changes their mind about something from an earlier phase, update the affected drafts before proceeding. - The agent being created must follow ALL conventions in `agents/CONVENTIONS.md`.