# Build Agents — arccrew

Build a complete multi-agent pipeline based on the user's description.

**User request:** $ARGUMENTS

---

Read these files fully before writing any code:
- `CLAUDE.md` — project structure, existing agents, conventions
- `skills/build-agents/SKILL.md` — pipeline patterns, state, agent code examples
- `skills/add-tool/SKILL.md` — how to create `@tool` functions correctly
- `skills/add-prompt/SKILL.md` — how to write agent prompts that actually work

## Step 1 — Understand the pipeline before designing it

Evaluate the user's request. A request is **detailed enough** if it answers all of these:
- What problem does the pipeline solve?
- What goes in, and what comes out?
- What steps/agents are needed?
- Does it need external tools (web, files, APIs)?

**If the request is vague** (e.g. "quiero algo para sheets", "a marketing pipeline", "help me process invoices"):
Do not guess. Run a guided interview — send all questions in a single message:

```
Before I design the pipeline, I need to understand what you're building:

1. **What does it do?** Describe the end-to-end flow in 2–3 sentences.
2. **What goes in?** What does the user/caller provide as input? (free text, a URL, a file path, structured data?)
3. **What comes out?** What should the final result contain? Who or what consumes it?
4. **What are the steps?** Can you describe the main processing stages? (e.g. "first it researches, then it writes, then it validates")
5. **Does it need external tools?** (web search, read/write files, call an API, send emails, etc.)
6. **Any constraints?** (language, tone, specific formats, compliance rules, etc.)
```

Wait for the user's answers before proceeding.

**If the request is detailed enough:** skip the interview and go straight to Step 2.

Never ask about things that have sensible defaults (model, max_rounds, state reducers).

## Step 2 — Present the blueprint (REQUIRED before any code)

Present a **Pipeline Blueprint** for the user to confirm. Show the data contract for every
agent — what it reads from state and what it writes back. This makes silent data-flow bugs
visible before a single line of code is written.

Estimate ReAct rounds per agent:
- Each tool call = ~2 rounds (call + result read)
- Formula: N items × M tool calls per item × 2 = estimated rounds
- > 10 rounds: recommend `AGENTNAME_MAX_ROUNDS` in `.env`
- > 20 rounds: suggest splitting the agent

```
## Pipeline Blueprint: {Pipeline Name}

**What it does:** one sentence

**Input:** what tasks[0].description contains (free text / JSON fields / etc.)

**Agents ({n} total):**
| Agent | Role | Reads from state | Tools | Est. rounds | Writes to state |
|-------|------|-----------------|-------|-------------|-----------------|
| AgentA | ... | tasks[idx].description | web_search | ~6 | context.research |
| AgentB | ... | context.research | none (LLM only) | ~2 | context.plan |
| AgentC | ... | context.plan | validate_post | ~8 | results |

**Flow:** AgentA → AgentB → AgentC → __end__

**Workload notes:** (round budget warnings, MAX_ROUNDS recommendations)

**Custom tools needed:**
- `tool_name(param: type) -> str` — what it does · file: tools/x.py
- (none if not needed)

**Custom state fields needed:**
- `field_name: dict` — why · reducer: _take_last_dict
- (none if not needed)

**Expected output** (what results[] contains):
[{"task_index": 0, "field1": "...", "field2": [...]}]

**Example curl:**
curl -X POST http://localhost:8000/api/runs \
  -H "Content-Type: application/json" \
  -d '{"pipeline": "name", "input": "example matching input shape above"}'
```

Ask: **"Does this look right? I'll generate all the files."**
Wait for confirmation before proceeding to Step 3.

## Step 3 — Generate all files

Apply the rules from the SKILL.md files read in Step 0:

| What to create | Rules from |
|----------------|------------|
| `tools/{custom}.py` | `skills/add-tool/SKILL.md` |
| `prompts/{agent}.md` | `skills/add-prompt/SKILL.md` |
| `agents/{agent}.py`, `pipeline.py`, `state.py` | `skills/build-agents/SKILL.md` |

Files to generate:
1. `tools/{custom}.py` — only if custom tools are needed
2. `prompts/{agent}.md` — one per agent
3. `agents/{agent}.py` — one per agent
4. `pipeline.py` — graph wiring + registration (API + MCP)
5. `state.py` — only if custom state fields are needed

## Non-negotiable rules

- Imports from `arccrew` only — never `src.*`
- `prompts/base.md` — never create or edit (library file)
- `prompts/global.md` — create if missing, never overwrite if exists
- Last agent MUST update `"results": [{"task_index": idx, **data}]` — this is what the API returns
- `async def` node wrappers in `pipeline.py` — never `lambda s: agent.execute(s)`
- Register pipeline in `pipeline.py`: both `pipeline_registry` and `register_pipeline`

## After generating

Update `CLAUDE.md` "Agents in this project":
```
- `AgentName` — one-line description → prompts/{agent}.md
```

Show the user:
```
Created:
  tools/{custom}.py      (if any)
  agents/{agent1}.py
  agents/{agent2}.py
  prompts/{agent1}.md
  prompts/{agent2}.md
  pipeline.py

.env recommendations:
  AGENTNAME_MAX_ROUNDS=25    (if agent has heavy workload)

Run:
  arccrew serve
  curl -X POST http://localhost:8000/api/runs \
    -H "Content-Type: application/json" \
    -d '{"pipeline": "{name}", "input": "your task description"}'
```
