# Aim Parzival Team Builder > Design agent team structure for parallel work execution - Skill: `hidden-history/aim-parzival-team-builder` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add hidden-history/aim-parzival-team-builder` - Raw SKILL.md: https://api.skillmd.com/api/skills/hidden-history/aim-parzival-team-builder/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Hidden-History (https://skillmd.com/u/hidden-history) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/hidden-history/aim-parzival-team-builder --- # Team Builder **Purpose**: Analyze work to be parallelized, design the appropriate team structure (single agent, 2-tier, or 3-tier), and produce a team design document ready for execution via the agent-dispatch cycle. **Note**: This skill is the entry point for team design. Parzival designs teams here, then executes them via the agent-dispatch workflow. Parzival activates agents himself -- the user does not run agents. > **HARD PROHIBITION**: This skill (aim-parzival-team-builder) MUST NEVER spawn or activate agents itself -- **including when it runs as `context: fork`**. It emits the dispatch plan ONLY. Parzival performs all dispatch via the agent-dispatch workflow. Even as a fork, this skill must not launch agents -- spawning from within this skill bypasses the agent-dispatch workflow and is forbidden. --- ## Fast Path: Single Agent The fast path trims the 6-step design for a single uncoordinated agent — it still emits a structured dispatch plan and routes through the full pipeline. ### Trigger Criteria (ALL must hold) - **Single agent**: exactly one executor, no lead/worker split - **No parallelization**: no peer agents, no file-ownership partitioning - **Clear file ownership**: every file the agent will touch is already known at dispatch time (no "will discover what to modify") - **Single review cycle**: at most one reviewer planned (dual review still permitted — see `reviewer_plan.mode`) - **No cross-cutting concerns**: the task does not force interface contracts with other in-flight work If any criterion fails, fall through to the full Team Design Process. ### Fast Path Execution 1. Collect provider and model preferences (Step 1b) 2. Assign agent role and AI_MEMORY_AGENT_ID (Step 2.3) 3. Prepare the context block (Step 4 format) 4. Emit the compact Dispatch Plan (see `Dispatch Plan Schema` below) for approval 5. On approval, route to `/aim-agent-dispatch` — the plan object is passed verbatim to the downstream skill **No activation greeting, no menu display, no multi-step analysis narration.** The fast path should read like a form, not a conversation. ### Fast Path Compact Output Example ```yaml # Dispatch Plan v1 provider: claude model: claude-sonnet-4-6 agent: dev agent_id: dev-auth bmad_agent_type: dev task_summary: "Implement Story 4.2 password-reset endpoint" files: - /abs/path/src/auth/reset.py - /abs/path/tests/test_reset.py workspace_root: /mnt/e/projects/dev-ai-memory complexity: moderate reviewer_plan: mode: single models: [claude-sonnet-4-6] route: aim-agent-dispatch # Approve? ``` --- ## Dispatch Plan Schema (v1) Every team-builder invocation — fast path, preset, or full design — emits a **Dispatch Plan** object. Downstream skills (`aim-agent-dispatch`, `aim-model-dispatch`) MUST accept this object as structured data and re-emit it verbatim to the next skill in the chain. **Goal**: model IDs like `glm-5.1:cloud` must survive the pipeline without paraphrase-corruption (no `glm-5`, no "use the latest glm"). File lists must not collapse to prose. ### Schema ```yaml # Dispatch Plan v1 provider: claude | openrouter | ollama | gemini | deepseek | groq | cerebras | mistral | openai | vertex-ai | siliconflow model: # verbatim, e.g., "glm-5.1:cloud", "claude-sonnet-4-6" agent: # dev | pm | architect | analyst | ux-designer | tech-writer | code-reviewer | agent_id: # e.g., "dev-auth", "review-opus", "architect-design" bmad_agent_type: | null # null ONLY for genuine non-BMAD work (code-reviewer, verify). If a BMAD role fits, null is a FAIL — assign the persona. task_summary: files: - - workspace_root: # MUST contain _ai-memory/ + _bmad/ + oversight/ complexity: straightforward | moderate | significant | complex reviewer_plan: mode: none | single | dual models: [, ] # empty list when mode=none route: aim-agent-dispatch # which dispatch skill to invoke next ``` ### Round-Trip Rules - **All keys always present.** Emit `null` or empty list for not-applicable fields rather than omitting the key — keeps schema stable. - **No paraphrasing.** When passing the plan to the next skill, copy the object as-is. Never reformat model IDs, never summarize file lists to "the auth files", never drop `agent_id` or `bmad_agent_type`. - **Validation gate.** The downstream skill MUST re-emit the plan unchanged in its first action. If a field is missing or malformed, STOP and request a corrected plan from the caller. - **Source of truth.** `workspace_root` is verified by the CWD sentinel in `aim-model-dispatch`. The plan is the record; the sentinel is the check. ### When Full Design Is Required The full 6-step Team Design Process emits one Dispatch Plan per team member plus a Team Document describing the overall structure. The fast path emits a single plan. Presets emit a preset-specific fan-out of plans. In all cases the schema above applies per-agent. --- ## Team Presets Before running the full 6-step design process, check if the work matches a preset. Presets are pre-validated team configurations for common patterns — they skip Steps 1-5 and go straight to confirmation. **How to use**: Match the user's request against the presets below. If it matches, present the preset with customizations (file paths, story IDs, model overrides). User approves → route directly to dispatch. If no preset matches, fall through to the full Team Design Process. ### Preset: Sprint Development (`sprint-dev`) **When**: 2-3 stories need parallel implementation with code review **Structure**: 2-tier — PM Lead (Opus) → 2 DEV workers (Sonnet) + 1 DEV reviewer (Opus) **Workflow commands**: Workers run `/bmad-dev-story`, reviewer runs `/bmad-code-review` **Requires**: sprint-status.yaml, architecture doc **Customize**: story assignments, file ownership per story ### Preset: Story Preparation (`story-prep`) **When**: Multiple stories need to be created from epics in bulk **Structure**: 2-tier — PM Lead (Opus) → 2-3 story-creation workers (Sonnet, run `/bmad-create-story`) **Workflow commands**: Workers run `/bmad-create-story` **Requires**: epics doc, sprint-status.yaml **Customize**: which stories to create, epic references ### Preset: Test Automation (`test-automation`) **When**: Completed stories need automated test coverage **Structure**: 2-tier — Architect Lead (Opus) → 2 test workers (Sonnet, run `/bmad-qa-generate-e2e-tests`) **Workflow commands**: Workers run `/bmad-qa-generate-e2e-tests` — generates automated API and E2E tests for completed story implementations **Requires**: sprint-status.yaml, bmm + tea modules installed **Customize**: which stories to test, test framework ### Preset: Architecture Review (`architecture-review`) **When**: Pre-sprint architecture work with parallel research **Structure**: 2-tier — Architect Lead (Opus) → Analyst worker (Sonnet) + UX Designer worker (Sonnet) **Workflow commands**: Analyst runs `/bmad-technical-research`, UX runs `/bmad-ux` **Requires**: PRD **Customize**: research focus areas, UX scope ### Preset: Research (`research`) **When**: Phase 1 parallel research across market, domain, and technical **Structure**: 2-tier — Analyst Lead (Opus) → 3 Analyst workers (Sonnet) **Workflow commands**: `/bmad-market-research`, `/bmad-domain-research`, `/bmad-technical-research` **Requires**: Nothing (recommended: project-context.md) **Customize**: research focus, industry, technology areas ### Preset Output Format When a preset matches, produce: ``` Preset Match: [preset name] Provider: [claude | openrouter | ollama | ...] Structure: [tier] — [lead] → [workers] Models: [role defaults or overrides] Stories/Tasks: [customized assignments] File Ownership: [per-worker paths] Workflow Commands: [per-worker commands] BMAD Agent Types: [per-worker bmad_agent_type, e.g. dev, pm; null for generic] Requires: [prerequisites — verify they exist] Approve? ``` Skip Steps 1-5. After user approval, route to dispatch. --- ## Team Design Process Use this full process when NO preset matches — custom team requirements, unusual agent combinations, or file ownership conflicts that presets don't handle. ### Step 1: Preflight Analysis 1. Read the work to be parallelized (plan, spec, or user description) 2. Identify independent work units that can run concurrently 3. Check for file ownership conflicts between units 4. Determine tier selection: | Scenario | Tier | Reasoning | |----------|------|-----------| | Single task | Single agent (fast path) | Overhead not justified | | 2-6 parallel tasks, single review | 2-Tier | Simple coordination | | 3+ domains, multi-task per domain, domain-level review | 3-Tier | Complex coordination | ### Step 1b: Provider and Model Preferences Ask the user: 1. **Provider**: Which LLM provider for this team? - claude, openrouter, ollama, gemini, deepseek, groq, cerebras, mistral, openai, vertex-ai, siliconflow 2. **Model tier**: Present role-based defaults (Opus for planning, Sonnet for execution). Ask if user wants to override any. Store provider and model selections in the dispatch plan. ### Step 2: Team Composition 1. Assign agent roles from available BMAD agents (analyst, pm, architect, dev, ux-designer, tech-writer) 2. Size teams: 3-5 teammates recommended, 5-6 tasks per teammate for productive sizing 3. **Assign agent identity**: Each agent MUST have a unique `AI_MEMORY_AGENT_ID`: - **Domain-named** (recommended): `dev-auth`, `dev-api`, `review-auth` -- same agent always works on same domain - **Numbered** (for generic work): `dev-1`, `dev-2`, `review-1` -- interchangeable agents - **Single-instance**: `pm`, `architect` -- use role name directly - Same `AI_MEMORY_AGENT_ID` across sessions enables cross-session memory accumulation 4. Select models per agent role: - Planning agents (Analyst, PM, Architect): Opus - Execution agents (DEV, review): Sonnet - Simple/high-volume tasks: Haiku Present defaults to user. Apply overrides if user requests. ### Step 3: File Ownership Map 1. Map every file that will be modified to exactly one agent 2. NO file ownership overlap between agents at any level 3. Cross-cutting concerns use interface contracts 4. Verify ownership map has zero conflicts before proceeding **Format**: Use a compact assignment list, not a matrix: ``` agent-name -> path/to/owned/files/** agent-name -> path/to/other/files/** Conflicts: NONE (or list conflicts found) ``` A sparse NxN matrix wastes tokens on columns of "—" entries. The assignment list conveys the same information. ### Step 4: Context Block Assembly For each agent, prepare: - ROLE: Agent type and assigned identity (AI_MEMORY_AGENT_ID) - BMAD AGENT TYPE: Intended BMAD agent type (`bmad_agent_type`), e.g. dev; null for generic, non-BMAD agents - TASK: Specific work items with acceptance criteria - FILES: Owned files (absolute paths) - CONSTRAINTS: "DO NOT modify any files outside your SCOPE list." — do not enumerate every other agent's files; the ownership map in Step 3 is the source of truth - DONE WHEN: Explicit completion criteria ### Step 5: Conflict Avoidance Strategy Select from ranked strategies (highest effectiveness first): 1. **Git Worktree Isolation** -- Each worker gets independent filesystem copy 2. **Exclusive File Ownership** -- Enforced by Step 3 ownership map 3. **Directory Partitioning** -- Workers own directories, not individual files 4. **Interface Contracts** -- For workers producing compatible code 5. **Merge-on-Green** -- Code merges to main only when all tests pass **Shared review-workspace collision (#284):** BMAD Validate skills write fixed-slug output (`review-{slug}.md`, `validation-report.md`) into their `doc_workspace`. Two Validate skills dispatched in parallel into the SAME `doc_workspace` silently overwrite each other's reports — and `_bmad-output/` is git-untracked, so the loss is unrecoverable. When dispatching two or more workspace-writing Validate skills in parallel, you MUST isolate their outputs: dispatch each validator in a separate git worktree (Strategy 1). A shared or subfoldered `doc_workspace` writes fixed-slug reports into git-untracked `_bmad-output/`, leaving cruft with no clean teardown; a worktree removes atomically. Never point two parallel validators at one workspace. **NEVER use file locking** -- collapsed 20 agents to throughput of 2-3 in production testing. **WSL2 note**: In-process mode recommended for WSL2 environments. tmux works best on macOS. ### Step 6: Pre-Delivery Review Before executing, verify: - [ ] All work units assigned to exactly one agent - [ ] No file ownership conflicts - [ ] Each agent has clear DONE WHEN criteria - [ ] Each agent has a unique AI_MEMORY_AGENT_ID assigned - [ ] Team size is 3-5 (split if larger) - [ ] Conflict avoidance strategy selected and documented - [ ] Context blocks are complete (no placeholders or TBDs) - [ ] No two parallel workspace-writing Validate skills share a `doc_workspace` (each validator in a separate git worktree — #284) --- ## Anti-Patterns - Never force 3-tier hierarchy when 2-tier suffices - Never allow file ownership overlap between agents - Never create teams without reading the codebase to verify boundaries - Never skip the pre-delivery review - Never let managers implement anything -- they orchestrate workers only - Never embed more than 4 worker prompts in a single manager context - Never allow unbounded review loops -- hard cap at 3 cycles, then escalate - Never spawn/activate agents from within this skill (even as a `context: fork`) -- emit the dispatch plan only; Parzival dispatches --- ## Output The team design document (Steps 1-6) is the deliverable. It feeds into the agent-dispatch cycle. **Do NOT assemble a copy-paste team prompt in the output.** The design document contains the context blocks (Step 4) and the templates are reference formats for dispatch. Prompt assembly happens at dispatch time — not here. **Templates:** - [`templates/team-prompt-2tier.template.md`](templates/team-prompt-2tier.template.md) — 2-tier team prompt format (lead + workers) - [`templates/team-prompt-3tier.template.md`](templates/team-prompt-3tier.template.md) — 3-tier team prompt format (lead + managers + workers) **Template placeholder fill-rules (dispatch-time assembly):** the 2-tier/3-tier templates carry two placeholder families that are NOT Step-4 context-block content — the dispatch-time assembler fills them from each agent's BMAD role so no raw placeholder survives into a rendered prompt: - `{*_activation}` (`{teammate_N_activation}`, `{manager_N_activation}`, `{worker_N_activation}`) = the Skill-tool-load activation string for that agent's BMAD role — e.g. `Use the Skill tool to load bmad-dev (the BMAD dev persona).` A bare `/bmad-*` at spawn activates the lead, not the persona, so the persona MUST be loaded via the Skill tool. - `{*_subagent_type}` (`{teammate_N_subagent_type}` / `{teammate_subagent_type}`, `{manager_N_subagent_type}` / `{manager_subagent_type}`) = `general-purpose` — the BMAD persona activates via the in-prompt Skill-load, not a native `subagent_type`. (Workers spawn via tmux `/aim-agent-lifecycle` and have no `subagent_type`.) Parzival activates all agents himself — the user does not run agents. **MANDATORY NEXT STEP**: After user approves the dispatch plan: - All agents (BMAD and generic) → /aim-agent-dispatch Pass the full Dispatch Plan object verbatim — including exact model ID, full file list, `agent_id`, and `bmad_agent_type` (see `Dispatch Plan Schema`). Downstream skills re-emit the plan for round-trip verification. (`bmad_agent_type` identifies the intended BMAD agent type, e.g. dev; null for generic agents.)