# {{PROJECT_NAME}}

This project was scaffolded with [arccrew](https://github.com/amonrreal/arccrew).

## Commands

```bash
arccrew check           # Verify config and dependencies
arccrew sync-skills     # Update skills after upgrading arccrew
arccrew serve           # Start API on port 8000
arccrew serve --reload  # Dev mode (hot reload)
arccrew serve-mcp       # Start MCP server for Claude Desktop and other MCP clients

pytest                    # Run tests
ruff check .              # Lint
```

## Architecture

Built on [arccrew](https://github.com/amonrreal/arccrew) — a multi-agent LangGraph framework.

### Request lifecycle

```
POST /api/run → PipelineRequest → pipeline.py graph → agents → PipelineResponse
```

### Key files

- `pipeline.py` — Graph definition. Register pipeline for API/MCP here.
- `agents/` — Agent classes. Each extends `arccrew.BaseAgent`.
- `tools/` — Custom `@tool` functions for this project. Import from `arccrew.tools` for built-ins.
- `prompts/` — Prompt files.
  - `global.md` — Rules applied to ALL agents in this project.
  - `{agent}.md` — Role, tools, and output schema for a specific agent.
- `tests/` — Tests for agents and tools.

### Prompt layers (applied in order)

| Layer | File | Who controls it |
|---|---|---|
| Base | `arccrew/prompts/base.md` | arccrew library |
| Global | `prompts/global.md` | **you** — project-wide rules |
| Agent | `prompts/{agent}.md` | **you** — agent-specific role |

Edit `prompts/global.md` to set rules that apply to every agent (tone, language, domain constraints).

### Built-in tools

```python
from arccrew.tools import get_research_tools, create_workspace_tools
from tools.calendar_tools import get_calendar_tools  # your domain-specific tools

# In any agent's execute():
result = await self.run_react(
    task=task,
    tools=get_research_tools() + get_calendar_tools(),
)
```

| Tool source | What it provides |
|---|---|
| `get_research_tools()` | `web_search` — DuckDuckGo search |
| `create_workspace_tools(path)` | `write_file`, `read_file`, `list_files`, `run_shell` |
| `tools/{domain}_tools.py` | Your domain-specific tools (e.g. `calendar_tools.py`) |

### Adding a new agent

Use the skill: `/add-agent <description>`

Or manually:

```python
# agents/my_agent.py
from arccrew import BaseAgent, track_timing
from arccrew.tools import get_research_tools
from langgraph.types import Command
from pathlib import Path

class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__(name="my_agent", prompts_dir=Path("prompts"))

    @property
    def system_prompt(self) -> str:
        return self.get_prompt_manager().assemble_prompt("my_agent")

    @track_timing
    async def execute(self, state: dict) -> Command:
        tasks = state.get("tasks", [])
        idx = state.get("current_task_index", 0)
        task = tasks[idx].get("description", "") if idx < len(tasks) else ""
        result = await self.run_react(task=task, tools=get_research_tools())
        return Command(goto="next_node", update={"result": self.extract_json(result)})
```

## Skills available

### Core
| Skill | What it does |
|---|---|
| `/build-agents` | Generate a full pipeline from a description |
| `/add-agent` | Add a single agent to an existing pipeline |
| `/add-tool` | Add a custom tool to an agent |
| `/add-state-field` | Add a custom state field with the right reducer |
| `/add-prompt` | Add or update an agent prompt |

### Patterns
| Skill | What it does |
|---|---|
| `/add-retry-loop` | Add retry + verification loop |
| `/add-review-gate` | Add a human-in-the-loop review gate |
| `/add-supervisor` | Add LLM-driven supervisor orchestration |

### Infrastructure
| Skill | What it does |
|---|---|
| `/add-api-endpoint` | Register a pipeline as a REST endpoint |
| `/add-mcp-pipeline` | Register a pipeline as an MCP tool |

### Configuration
| Skill | What it does |
|---|---|
| `/configure-claude` | Configure Claude as LLM provider |
| `/configure-openai` | Configure OpenAI as LLM provider |
| `/configure-gemini` | Configure Gemini as LLM provider |
| `/switch-provider` | Switch between LLM providers |

### Quality
| Skill | What it does |
|---|---|
| `/enable-langsmith` | Set up LangSmith tracing |
| `/enable-otel` | Set up OpenTelemetry (Grafana, Datadog, Jaeger…) |
| `/debug-pipeline` | Diagnose pipeline errors |
| `/write-tests` | Generate tests for agents and tools |

## Agents in this project

<!-- arccrew updates this section automatically when you use /add-agent -->
