# Chronis AI Agents

A self-hosted, multi-tenant AI agent platform. Specialised agents (Sales first) prospect, research, and draft outreach, with human-in-the-loop approval via Slack. Built with Laravel + Livewire, OpenRouter for LLM routing, and Docker Compose for self-hosting.

> **Read `CLAUDE.md` first.** It is the master context file and encodes the non-negotiable architecture rules. `docs/PRD.md` is the full spec; `docs/design-system.md` is the visual + UX guide.

---

## What's in this scaffold

This is a **starting skeleton**, not the finished app. It gives Claude Code a structured, opinionated foundation so it continues an existing project rather than building from a cold spec. Included:

```
chronis-ai-agents/
├── CLAUDE.md                       <- master context, read on launch
├── docker-compose.yml              <- app, nginx, postgres, redis, horizon, scheduler
├── .env.example                    <- all required env vars
├── config/openrouter.php           <- model tiering config
├── docs/
│   ├── PRD.md                      <- full product + technical spec (v2, reviewed)
│   └── design-system.md            <- design tokens, components, UX, accessibility
├── database/migrations/            <- the architecture-critical tables (examples)
│   ├── ...companies
│   ├── ...skills (typed: context/evaluator/transformer/tool)
│   ├── ...agent_runs + idempotency_keys
│   └── ...sequences + sequence_steps
└── app/Services/
    ├── LLM/OpenRouterClient.php    <- LLM calls with usage/cost capture
    ├── LLM/LlmResponse.php
    ├── Agent/AgentEngine.php       <- the PIPELINE executor (heart of the system)
    ├── Agent/BudgetGuard.php       <- atomic USD budget guard
    └── Skills/
        ├── Skill.php               <- the typed-skill contract
        ├── SkillContext.php        <- mutable pipeline state
        ├── IcpMatcherSkill.php     <- example EVALUATOR (can short-circuit)
        └── HumanizerSkill.php      <- example TRANSFORMER
```

The remaining ~16 tables, models, jobs, integrations, and all UI are fully specified in `docs/PRD.md` and built by Claude Code (see "First tasks" below).

---

## Part 1 — Install Claude Code

You need three things before installing: **Node.js v18+**, a **Claude subscription or API key**, and **Git**. On Windows, use WSL2.

### 1. Check Node.js
```bash
node --version    # must be v18.0.0 or higher
```
If missing, install the LTS from nodejs.org (or use `nvm`), then **open a fresh terminal**.

### 2. Install Claude Code
Either the native installer (no Node needed) or npm:
```bash
npm install -g @anthropic-ai/claude-code
```

### 3. Verify + authenticate
```bash
claude --version
claude        # launches; first run walks you through browser OAuth login
```
A Claude Pro or Max subscription covers terminal usage; alternatively set `ANTHROPIC_API_KEY` for API-based auth.

### 4. (Optional) Cursor alongside
Open this same folder in Cursor as your editor. No migration, no export — Claude Code (terminal) and Cursor (editor) operate on the same Git repo simultaneously. Use Claude Code for multi-file agentic work, Cursor for inline edits.

---

## Part 2 — Bootstrap the project

This scaffold has the structure and core services but not a full Laravel install yet. From inside the project folder, launch Claude Code:

```bash
cd chronis-ai-agents
git init && git add -A && git commit -m "Initial scaffold"
claude
```

Then give it this first instruction:

> Read CLAUDE.md, docs/PRD.md, and docs/design-system.md. This repo is a scaffold with core services already written (app/Services). Install Laravel 11 into this existing structure without overwriting CLAUDE.md, docs/, the existing app/Services classes, the migrations in database/migrations, config/openrouter.php, docker-compose.yml, or .env.example. Then wire Livewire 3, Horizon, and the PostgreSQL/Redis connections to match docker-compose.yml. Follow the build order in CLAUDE.md. Start with step 1 (Docker + skeleton + multi-company auth) and stop for my review before step 2.

### 3. Bring the stack up
```bash
cp .env.example .env
docker compose up -d --build
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate
```
App runs at http://localhost:8080. Horizon dashboard at /horizon.

---

## Part 3 — Recommended first tasks (in order)

Work through these with Claude Code one at a time, reviewing each before moving on:

1. **Laravel skeleton + multi-company auth** — global scopes, role middleware
2. **Remaining migrations + Eloquent models** — per PRD §4 (agents, agent_tasks, approvals, memories, integrations, integration_secrets, icps, events, audit_logs, feedback_signals, notifications)
3. **SkillResolver + RunAgentJob** — build Skill objects from agent_skills rows, run through AgentEngine, persist agent_runs/agent_tasks, wire BudgetGuard to the Agent model
4. **Approval workflow** — Slack Block Kit message, signature-verified webhook, expiry, ExecuteTaskJob (idempotency-guarded)
5. **Sales agent** — seed Mailblaze ICP + default sequence, build the 7 skills, integrations (Apollo, Pipedrive, Mailblaze send, Gmail/IMAP replies)
6. **UI** — dashboard, agent config, approvals queue, edit-before-send, skills pipeline, sequences editor — strictly following docs/design-system.md, as reusable Blade components

---

## Keys you'll need before agents can run
- `OPENROUTER_API_KEY` — get from openrouter.ai
- `SLACK_BOT_TOKEN` + `SLACK_SIGNING_SECRET` — Slack app for approvals
- `PIPEDRIVE_API_KEY`, `APOLLO_API_KEY`, `MAILBLAZE_API_KEY`
- `GMAIL_CLIENT_ID` + `GMAIL_CLIENT_SECRET` — for reply detection (Mailblaze can't do this)

---

## The rules that matter most (also in CLAUDE.md)
1. Skills are typed and run as a pipeline — never one mega-prompt.
2. Every external write is idempotency-guarded.
3. Follow-up cadence is data (sequences), not hardcoded.
4. Reply detection uses Gmail/IMAP, not Mailblaze.
5. Budgets in USD, checked atomically before each LLM call.
6. POPIA/GDPR: opt-out, retention, unsubscribe.
7. Approvals expire; nothing sends late or silently.