Skip to content

Commit b6ed39d

Browse files
vincentgroblervincentgrobler
authored
Merge pull request #39 from vincentgrobler/feature/ticket-6.4-documentation
docs(ticket-6.4): comprehensive documentation suite
2 parents 6b99cbe + 881c5f3 commit b6ed39d

5 files changed

Lines changed: 569 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
- [Why CrewForm?](#why-crewform)
2222
- [Key Features](#key-features)
2323
- [Quick Start](#quick-start)
24+
- [Documentation](#documentation)
2425
- [Architecture](#architecture)
2526
- [Tech Stack](#tech-stack)
2627
- [How CrewForm Compares](#how-crewform-compares)
@@ -71,7 +72,17 @@ cp .env.example .env.local
7172
npm run dev
7273
```
7374

74-
> **Self-hosting?** See our [Docker deployment guide](https://docs.crewform.tech/self-hosting) for production setup.
75+
> **Self-hosting?** See the [Docker deployment guide](docs/self-hosting.md) for production setup.
76+
77+
## Documentation
78+
79+
| Guide | Description |
80+
|-------|-------------|
81+
| [Quick Start](docs/quickstart.md) | Get running in under 5 minutes |
82+
| [Agents Guide](docs/agents.md) | Models, system prompts, and agent lifecycle |
83+
| [Pipeline Teams](docs/pipeline-teams.md) | Multi-agent workflows and handoffs |
84+
| [API Reference](docs/api-reference.md) | REST API endpoints and authentication |
85+
| [Self-Hosting](docs/self-hosting.md) | Docker Compose production deployment |
7586

7687
## Architecture
7788

‎docs/agents.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Agents Guide
2+
3+
Agents are the core building blocks of CrewForm. Each agent is an AI worker configured with a specific model, system prompt, and capabilities.
4+
5+
## Creating an Agent
6+
7+
Navigate to **Agents → New Agent** or use the `+` button.
8+
9+
### Required Fields
10+
11+
| Field | Description |
12+
|-------|-------------|
13+
| **Name** | Human-readable identifier (e.g., "Code Reviewer") |
14+
| **Model** | LLM model to use (see [Supported Models](#supported-models)) |
15+
| **System Prompt** | Instructions that define the agent's behavior |
16+
17+
### Optional Fields
18+
19+
| Field | Description |
20+
|-------|-------------|
21+
| **Description** | What the agent does (shown in marketplace) |
22+
| **Temperature** | Creativity level (0.0 = deterministic, 1.0 = creative) |
23+
| **Max Tokens** | Maximum response length |
24+
| **Tags** | Categorization for search and marketplace |
25+
26+
## Supported Models
27+
28+
CrewForm supports three LLM providers. You must add your API key in **Settings → API Keys** before using a provider.
29+
30+
### Anthropic (Claude)
31+
32+
| Model | Best For |
33+
|-------|----------|
34+
| `claude-sonnet-4-20250514` | General-purpose, balanced cost/quality |
35+
| `claude-3-5-haiku-20241022` | Fast, cost-effective tasks |
36+
| `claude-3-opus-20240229` | Complex reasoning, analysis |
37+
38+
### Google (Gemini)
39+
40+
| Model | Best For |
41+
|-------|----------|
42+
| `gemini-2.0-flash` | Fast, multimodal tasks |
43+
| `gemini-1.5-pro` | Long-context, complex tasks |
44+
45+
### OpenAI (GPT)
46+
47+
| Model | Best For |
48+
|-------|----------|
49+
| `gpt-4o` | General-purpose, fast |
50+
| `gpt-4-turbo` | Complex reasoning |
51+
| `gpt-3.5-turbo` | Simple, high-volume tasks |
52+
53+
## Writing System Prompts
54+
55+
The system prompt defines your agent's personality, expertise, and output format. Tips:
56+
57+
### Be Specific
58+
59+
```
60+
❌ "You are a helpful assistant."
61+
✅ "You are a senior code reviewer specializing in TypeScript and React.
62+
You review code for bugs, performance issues, and best practices.
63+
Output your review as a numbered list with severity (HIGH/MEDIUM/LOW)."
64+
```
65+
66+
### Define Output Format
67+
68+
```
69+
You must respond in the following JSON format:
70+
{
71+
"summary": "one-line summary",
72+
"findings": [{ "severity": "HIGH|MEDIUM|LOW", "description": "..." }],
73+
"recommendation": "overall recommendation"
74+
}
75+
```
76+
77+
### Set Boundaries
78+
79+
```
80+
You ONLY review code. If asked to write new code, respond with:
81+
"I'm configured as a reviewer. Please create a separate coding agent."
82+
```
83+
84+
## Agent Lifecycle
85+
86+
```
87+
Created → Idle → Running (task assigned) → Idle
88+
↓
89+
Failed (error)
90+
```
91+
92+
- **Idle**: Ready to accept tasks
93+
- **Running**: Actively processing a task
94+
- **Failed**: Task errored — check the task detail for the error message
95+
96+
## Using Agents in Teams
97+
98+
Agents become more powerful when combined into teams. See the [Pipeline Teams Guide](./pipeline-teams.md) for multi-agent workflows.
99+
100+
## API Key Security
101+
102+
All API keys are encrypted with **AES-256-GCM** before storage. Keys are:
103+
104+
- Encrypted client-side before being sent to the database
105+
- Never stored in plaintext
106+
- Only decrypted by the task runner at execution time
107+
- Scoped to your workspace via Row-Level Security
108+
109+
See [Settings → API Keys] in the app to manage your provider keys.

‎docs/api-reference.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
# REST API Reference
2+
3+
CrewForm exposes a REST API via Supabase for programmatic access to your workspace. Authenticate using API keys created in **Settings → API Keys**.
4+
5+
## Authentication
6+
7+
All API requests require a REST API key in the `Authorization` header:
8+
9+
```bash
10+
curl -H "Authorization: Bearer crfm_your_api_key" \
11+
-H "Content-Type: application/json" \
12+
https://your-project.supabase.co/rest/v1/agents
13+
```
14+
15+
### Creating API Keys
16+
17+
1. Go to **Settings → API Keys**
18+
2. Click **Generate Key**
19+
3. Copy the key — it's only shown once
20+
4. The key is hashed (SHA-256) before storage for security
21+
22+
## Endpoints
23+
24+
All endpoints are accessed via the Supabase REST API at:
25+
26+
```
27+
https://<your-project>.supabase.co/rest/v1/<table>
28+
```
29+
30+
You also need the `apikey` header with your Supabase anon key:
31+
32+
```bash
33+
curl -H "Authorization: Bearer crfm_your_api_key" \
34+
-H "apikey: your-supabase-anon-key" \
35+
https://your-project.supabase.co/rest/v1/agents
36+
```
37+
38+
---
39+
40+
## Agents
41+
42+
### List Agents
43+
44+
```http
45+
GET /rest/v1/agents?select=*
46+
```
47+
48+
**Response:**
49+
50+
```json
51+
[
52+
{
53+
"id": "uuid",
54+
"name": "Code Reviewer",
55+
"description": "Reviews code for bugs and best practices",
56+
"model": "claude-sonnet-4-20250514",
57+
"provider": "anthropic",
58+
"system_prompt": "You are a senior code reviewer...",
59+
"temperature": 0.3,
60+
"max_tokens": 4096,
61+
"tags": ["code", "review"],
62+
"workspace_id": "uuid",
63+
"created_at": "2026-01-15T10:00:00Z",
64+
"updated_at": "2026-01-15T10:00:00Z"
65+
}
66+
]
67+
```
68+
69+
### Create Agent
70+
71+
```http
72+
POST /rest/v1/agents
73+
Content-Type: application/json
74+
75+
{
76+
"name": "Code Reviewer",
77+
"model": "claude-sonnet-4-20250514",
78+
"provider": "anthropic",
79+
"system_prompt": "You are a senior code reviewer...",
80+
"workspace_id": "your-workspace-id"
81+
}
82+
```
83+
84+
### Update Agent
85+
86+
```http
87+
PATCH /rest/v1/agents?id=eq.{agent_id}
88+
Content-Type: application/json
89+
90+
{
91+
"name": "Updated Name",
92+
"temperature": 0.5
93+
}
94+
```
95+
96+
### Delete Agent
97+
98+
```http
99+
DELETE /rest/v1/agents?id=eq.{agent_id}
100+
```
101+
102+
---
103+
104+
## Tasks
105+
106+
### List Tasks
107+
108+
```http
109+
GET /rest/v1/tasks?select=*&order=created_at.desc
110+
```
111+
112+
**Query parameters for filtering:**
113+
114+
| Parameter | Example | Description |
115+
|-----------|---------|-------------|
116+
| `status` | `eq.running` | Filter by status |
117+
| `priority` | `eq.high` | Filter by priority |
118+
| `agent_id` | `eq.{uuid}` | Filter by assigned agent |
119+
120+
### Create Task
121+
122+
```http
123+
POST /rest/v1/tasks
124+
Content-Type: application/json
125+
126+
{
127+
"title": "Review PR #42",
128+
"description": "Review the authentication changes",
129+
"agent_id": "uuid",
130+
"priority": "high",
131+
"workspace_id": "your-workspace-id"
132+
}
133+
```
134+
135+
**Task statuses:** `pending`, `running`, `completed`, `failed`, `cancelled`
136+
137+
**Task priorities:** `low`, `medium`, `high`, `critical`
138+
139+
### Get Task Detail
140+
141+
```http
142+
GET /rest/v1/tasks?id=eq.{task_id}&select=*
143+
```
144+
145+
---
146+
147+
## Teams
148+
149+
### List Teams
150+
151+
```http
152+
GET /rest/v1/teams?select=*
153+
```
154+
155+
### Create Team
156+
157+
```http
158+
POST /rest/v1/teams
159+
Content-Type: application/json
160+
161+
{
162+
"name": "Content Pipeline",
163+
"description": "Research → Write → Edit",
164+
"mode": "pipeline",
165+
"workspace_id": "your-workspace-id"
166+
}
167+
```
168+
169+
### Team Runs
170+
171+
```http
172+
GET /rest/v1/team_runs?team_id=eq.{team_id}&select=*&order=created_at.desc
173+
```
174+
175+
---
176+
177+
## Usage Records
178+
179+
### Query Usage
180+
181+
```http
182+
GET /rest/v1/usage_records?select=*&created_at=gte.2026-01-01&order=created_at.desc
183+
```
184+
185+
**Response fields:**
186+
187+
| Field | Type | Description |
188+
|-------|------|-------------|
189+
| `task_id` | uuid | Associated task |
190+
| `agent_id` | uuid | Agent that ran |
191+
| `provider` | string | LLM provider |
192+
| `model` | string | Model used |
193+
| `prompt_tokens` | integer | Input tokens |
194+
| `completion_tokens` | integer | Output tokens |
195+
| `estimated_cost_usd` | decimal | Estimated cost |
196+
| `billing_model` | string | `per-token` or `subscription-quota` |
197+
198+
---
199+
200+
## Marketplace
201+
202+
### Browse Agents
203+
204+
```http
205+
GET /rest/v1/agents?is_marketplace=eq.true&select=*
206+
```
207+
208+
### Install Agent (RPC)
209+
210+
```http
211+
POST /rest/v1/rpc/increment_install_count
212+
Content-Type: application/json
213+
214+
{
215+
"agent_row_id": "uuid"
216+
}
217+
```
218+
219+
---
220+
221+
## Rate Limits
222+
223+
The Supabase free tier includes:
224+
- **500 requests/minute** per API key
225+
- **50,000 requests/month** total
226+
227+
For higher limits, upgrade your Supabase plan.
228+
229+
## Error Handling
230+
231+
All errors follow the standard Supabase/PostgREST format:
232+
233+
```json
234+
{
235+
"code": "PGRST301",
236+
"message": "Row not found",
237+
"details": null,
238+
"hint": null
239+
}
240+
```
241+
242+
Common error codes:
243+
244+
| HTTP Status | Meaning |
245+
|-------------|---------|
246+
| `401` | Missing or invalid API key |
247+
| `403` | Row-Level Security denied access |
248+
| `404` | Resource not found |
249+
| `409` | Conflict (duplicate key) |
250+
| `422` | Validation error |

0 commit comments

Comments
 (0)