# Workflow: Creating ConnectOnion Agents

**When a user describes a problem, create a ConnectOnion agent to solve it.**

## Decision Tree

```
User wants an agent
        │
        ▼
┌─────────────────────────────┐
│ New project or existing?    │
└───────────┬─────────────────┘
            │
    ┌───────┴───────┐
    │New project    │Existing folder
    ▼               ▼
  co create       co init
  <name>          (adds .co/ and .env)
    │               │
    └───────┬───────┘
            ▼
┌─────────────────────────────┐
│ Does a template exist?      │
│ (playwright, email-agent,   │
│  web-research, meta-agent)  │
└───────────┬─────────────────┘
            │
    ┌───────┴───────┐
    │Yes            │No
    ▼               ▼
  co create    ┌─────────────────────────┐
  --template   │ Is it simple (2-4 tools)?│
               └───────────┬─────────────┘
                           │
                   ┌───────┴───────┐
                   │Yes            │No (5+ tools)
                   ▼               ▼
             Write agent.py   load_guide("agent-design")
             (one file)       then write with class
```

## Step 1: Always Setup Project First

**New project → `co create`:**
```bash
co create cleaner
cd cleaner
# Now has:
#   .co/         # metadata
#   .env         # API keys
#   agent.py     # your code
#   prompt.md    # system prompt
```

**Existing folder → `co init`:**
```bash
cd /tmp/file-cleaner
co init
# Now has: .co/, .env, agent.py, prompt.md
```

**With template:**
```bash
co create browser-bot --template playwright
co create email-assistant --template email-agent
co create researcher --template web-research
```

## Step 2: Edit the Template Files

**After `co create`, files exist. Use `edit` tool (not `write`) to modify them:**

```python
# agent.py
from connectonion import Agent

def list_files(dir: str) -> list[str]:
    """List all files in directory."""
    from pathlib import Path
    return [str(f) for f in Path(dir).iterdir() if f.is_file()]

def get_hash(path: str) -> str:
    """Get MD5 hash of a file."""
    import hashlib
    return hashlib.md5(open(path, 'rb').read()).hexdigest()

def delete_file(path: str) -> str:
    """Delete a file."""
    import os
    os.remove(path)
    return f"Deleted {path}"

agent = Agent("cleaner", system_prompt="prompt.md", tools=[list_files, get_hash, delete_file])

if __name__ == "__main__":
    agent.input("Find and remove duplicate files in /downloads")
```

```markdown
# prompt.md
You are a file cleaner agent. Find duplicate files by comparing hashes and remove them safely.
```

**Complex (5+ tools) → Load guide first:**
```python
load_guide("agent-design")  # Then follow class pattern
```

## Step 3: Done

Say: "Done. Run with `python agent.py`"

---

## NEVER DO THIS

```python
# BAD: Using write tool on existing files (use edit instead)
write("agent.py", "...")  # ← WRONG, file exists after co create

# BAD: Writing agent.py without project setup (no .env = no API key)
# Just write /tmp/cleaner.py  ← WRONG, need co create first

# BAD: Standalone script with argparse (not an agent)
import argparse
def main():
    parser = argparse.ArgumentParser()
    # ... hardcoded logic ...

# BAD: Markdown file instead of Python
# /tmp/cleaner.agent.md  ← WRONG, write .py not .md
```

## Key Rules

1. **`co create` or `co init` first** - Agent needs .co/ and .env for API keys
2. **Use `edit` tool for existing files** - After `co create`, template files exist. Edit them, don't overwrite with `write`
3. **Write .py files, NOT .md files** - Agents are Python code
4. **from connectonion import Agent** - Always use the framework
5. **Atomic tools** - Each function does ONE thing
6. **No asking, no explaining** - Just setup project, edit code, say "Done"
