---
name: predev
description: Use when building or modifying software with AI agents, generating specifications and implementation plans, automating browser workflows, or integrating AI capabilities into applications. Agents should reach for this skill when users request code implementation, architecture planning, browser automation, or when building integrations with pre.dev's APIs.
metadata:
    mintlify-proj: predev
    version: "1.0"
---

# pre.dev Skill Reference

## Product summary

pre.dev is an AI-powered development platform with four primary interfaces: the **Coding Agent** (web workspace or CLI) for implementing code changes, the **Architect API** for generating specifications and implementation plans, **Browser Agents** for automating web workflows and data extraction, and the **AI Gateway** for inference across hundreds of models. All interfaces use the same API key (`PREDEV_API_KEY`) and credit system. Access the platform at https://pre.dev, the API at `https://api.pre.dev`, and the MCP server at `https://api.pre.dev/mcp`. The CLI is installed via `curl -fsSL https://pre.dev/install | bash`. Key files: project configuration lives in the web workspace or CLI project directory; environment variables are managed in Project setup (`/integrations`); API keys are retrieved at `pre.dev/projects/key`.

## When to use

Reach for this skill when:
- A user asks to build, modify, or fix code in a new or existing project
- A user needs a software specification, architecture plan, or implementation roadmap
- A user wants to automate browser tasks: extract data, fill forms, navigate pages, verify behavior
- A user needs to integrate AI capabilities (chat, embeddings, image generation) into an application
- A user is building an integration with pre.dev's REST API, SDKs, or MCP server
- A user needs to verify code changes with acceptance criteria or browser verification
- A user wants to plan work before implementation or coordinate a larger project

Do not use this skill for: account management, billing, pricing decisions, or dashboard-only operations.

## Quick reference

### Interfaces and entry points

| Task | Interface | Start with |
| --- | --- | --- |
| Build or modify code | Web workspace or CLI | `https://pre.dev` or `predev` command |
| Generate a specification | REST API or MCP | `POST /fast-spec` or `POST /deep-spec` |
| Run browser tasks | REST API, SDK, or MCP | `POST /browser-agent` |
| Use AI models for inference | AI Gateway | `https://api.pre.dev/v1` (OpenAI-compatible) |
| Connect from another AI assistant | MCP server | `https://api.pre.dev/mcp` |

### CLI commands (terminal)

| Command | Purpose |
| --- | --- |
| `predev` | Launch in current directory |
| `predev --new` | Create fresh project association |
| `/auto` | Let agent choose next step (default) |
| `/plan` | Focus on requirements and architecture |
| `/sprint <feature>` | Dedicated sprint for a defined feature |
| `/fork <prompt>` | Separate session for isolated task |
| `/effort` | Set to auto, low, medium, or high |
| `/integrations` | Open Project setup (connections, skills, MCP, env vars) |
| `/skills`, `/mcp` | Manage personal integrations |
| `/arch`, `/kanban`, `/roadmap` | View project planning |
| `/balance` | Check remaining credits |

### REST API base URLs and authentication

```bash
# Specifications and browser agents
https://api.pre.dev

# AI Gateway (OpenAI-compatible)
https://api.pre.dev/v1

# Authentication (both headers accepted)
Authorization: Bearer $PREDEV_API_KEY
x-api-key: $PREDEV_API_KEY
```

### Core REST endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/fast-spec` | Generate concise specification (milestones + stories) |
| POST | `/deep-spec` | Generate detailed specification (milestones + stories + subtasks) |
| GET | `/spec-status/{specId}` | Poll specification status and retrieve artifacts |
| POST | `/browser-agent` | Submit browser tasks (extract, navigate, fill forms) |
| GET | `/browser-agent/{id}` | Poll browser task status and results |
| GET | `/browser-agent/{id}/stream` | Stream existing run with SSE |
| GET | `/credits-balance` | Check available credits |

### Specification request body (REST)

```json
{
  "input": "What to build (required, 10+ chars)",
  "currentContext": "Existing codebase description (optional)",
  "docURLs": ["https://example.com/docs"],
  "async": true
}
```

### Browser task request body (REST)

```json
{
  "tasks": [
    {
      "url": "https://example.com",
      "instruction": "What to do",
      "output": {
        "type": "object",
        "properties": { "field": { "type": "string" } },
        "required": ["field"]
      },
      "mode": "auto"
    }
  ],
  "async": true
}
```

### SDK imports

```typescript
// Node.js
import { PredevAPI } from 'predev-api';
const client = new PredevAPI({ apiKey: process.env.PREDEV_API_KEY });

// Python
from predev_api import PredevAPI
client = PredevAPI(api_key=os.environ["PREDEV_API_KEY"])
```

## Decision guidance

### When to use Fast Spec vs Deep Spec

| Choose | When |
| --- | --- |
| Fast Spec | Explore scope, validate an idea, establish first architecture, or need quick results (~1 min, 5–10 credits) |
| Deep Spec | Coordinate larger projects, examine implementation details, or need granular subtasks (~3–5 min, 10–50 credits) |

### When to use Auto vs Plan mode

| Mode | Use when |
| --- | --- |
| Auto (default) | You want the agent to decide: answer questions, implement directly, or plan first |
| Plan | You want to shape requirements, user flows, roadmap, and architecture before implementation |

### When to use Web vs CLI

| Surface | Use when |
| --- | --- |
| Web workspace | Creating new projects, importing GitHub repos, reviewing plans, using hosted previews, managing team settings |
| CLI | Working in local repository, reviewing changes with Git, using existing development workflow, managing personal integrations |

### When to use REST vs MCP vs SDK

| Interface | Use when |
| --- | --- |
| REST | Building custom integrations, need full control, or using languages without SDK |
| MCP | Connecting pre.dev to another AI assistant or using with Claude/other LLM clients |
| SDK (Node/Python) | Building applications in Node.js or Python, want type safety and error handling |

### When to use sync vs async submission

| Mode | Use when |
| --- | --- |
| Sync (default) | Task is quick, you can wait for response, or testing |
| Async | Task may take time, you need to poll, or want to submit multiple tasks without blocking |

## Workflow

### Typical Coding Agent workflow (web or CLI)

1. **Describe the outcome**: State what behavior you want, relevant context, and constraints. Include acceptance criteria (observable behavior that should hold).
2. **Choose your approach**: Use Auto (default) to let the agent decide, or `/plan` to shape requirements first.
3. **Connect integrations**: Open `/integrations` to enable skills, MCP servers, API keys, and environment variables the project needs.
4. **Build and verify**: Request implementation with `/sprint` for dedicated work. Review the verification report and checks that ran.
5. **Review and ship**: Inspect the diff, test the preview, then merge or deploy using your repository's workflow.

### Typical Architect API workflow (REST or MCP)

1. **Submit specification request**: POST to `/fast-spec` or `/deep-spec` with `input` (required), `currentContext` (optional), and `async: true`.
2. **Save the spec ID**: Extract `specId` from the response.
3. **Poll for completion**: GET `/spec-status/{specId}` every 5 seconds until `status` is `completed` or `failed`.
4. **Read artifacts**: On success, consume `codingAgentSpecMarkdown` (for implementation), `humanSpecMarkdown` (for review), or `codingAgentSpecJson` (for structured data).
5. **Handle failure**: If `status` is `failed`, read `error` and `errorDetails` to understand what went wrong.

### Typical Browser Agent workflow (REST or MCP)

1. **Define tasks**: Create a `tasks` array with `url`, `instruction`, and optional `output` JSON Schema.
2. **Submit with async**: POST to `/browser-agent` with `async: true` to get the run ID immediately.
3. **Save the run ID**: Extract `id` from the response.
4. **Poll for completion**: GET `/browser-agent/{id}` every 5 seconds until batch `status` is `completed` or `failed`.
5. **Check each task**: Iterate `results` array; check each task's `status` before reading `data`.
6. **Handle failures**: Failed tasks have `status` != `SUCCESS` and an `error` field; successful tasks have `status: "SUCCESS"` and `data`.

### Using MCP with another AI assistant

1. **Connect the MCP server**: Add `https://api.pre.dev/mcp` to your client's remote HTTP servers.
2. **Authenticate**: Use the client's OAuth flow; sign in and select your account.
3. **Discover tools**: Call `tools/list` to see available tools and their input schemas.
4. **Use tools**: Call `fast_spec`, `deep_spec`, `get_spec`, `browser_agent`, etc. with the parameters shown.
5. **Handle results**: MCP tools return text or structured content; check for `isError` or `error` fields.

## Common gotchas

- **Polling without stopping**: Always stop polling when `status` is `completed` or `failed`. Polling indefinitely wastes credits and time.
- **Ignoring task status in browser results**: A batch can return HTTP 200 with `status: "completed"` but individual tasks can still fail. Always check each task's `status` before reading `data`.
- **Submitting without async for long tasks**: Synchronous requests time out. Use `async: true` for any task that might take more than a few seconds.
- **Not saving the run/spec ID**: If you lose the ID, you cannot retrieve results. Save it immediately after submission.
- **Assuming output schema is optional**: If your code depends on a specific data shape, always provide an `output` JSON Schema. Without it, the service may infer a different structure.
- **Forgetting to include acceptance criteria**: State observable behavior in your request so the agent knows what to verify. "Add a filter" is vague; "add a filter that works with other filters and shows an empty state" is testable.
- **Not checking queue status before large batches**: Browser tasks have a 1,000-task request ceiling and per-account in-flight limits. Call `GET /browser-agent-status` before submitting large workloads.
- **Resubmitting without checking existing work**: A timeout or disconnected stream does not prove the task stopped. Retrieve the existing run by ID before submitting again.
- **Passing spec ID as currentContext**: `currentContext` is text describing the codebase, not an ID that loads another project. Paste the spec's Markdown or JSON if you want to refine it.
- **Ignoring error codes**: Browser submission errors include machine-readable `code` fields (e.g., `INSUFFICIENT_CREDITS`, `QUEUE_FULL`). Read the code to determine the right next step.
- **Not toggling integrations before work starts**: Skills, MCP servers, and API keys must be enabled before the task starts. Enabling them mid-task does not reload them.
- **Assuming MCP parameter names match REST**: MCP uses `executiveSummary` instead of `input`, `existingContext` instead of `currentContext`. Check the tool schema.

## Verification checklist

Before submitting work or considering a task complete:

- [ ] **Acceptance criteria are defined**: State observable behavior in the request (e.g., "filter works with other filters", "empty state shows helpful message").
- [ ] **Integrations are enabled**: Open `/integrations` and confirm skills, MCP servers, API keys, and env vars are toggled on and configured.
- [ ] **API key is valid**: Confirm `PREDEV_API_KEY` is set and retrieved from `pre.dev/projects/key`.
- [ ] **Async submission saved the ID**: For long-running work, extract and save `specId` or `id` immediately after submission.
- [ ] **Polling stopped at terminal state**: Confirm you stopped polling when `status` is `completed` or `failed`, not based on time or array length.
- [ ] **Task status was checked**: For browser results, verify each task's `status` is `SUCCESS` before reading `data`.
- [ ] **Error codes were handled**: If submission failed, read the `code` field to determine whether to retry, fix input, or check account access.
- [ ] **Verification report was reviewed**: Read the actual checks that ran, not just the final status. Skipped checks and blockers should be noted.
- [ ] **Diff was inspected**: Review code changes before merging or deploying.
- [ ] **Preview was tested**: If available, test the feature in the preview environment against your acceptance criteria.

## Resources

- **Full documentation index**: https://docs.pre.dev/llms.txt — comprehensive page-by-page navigation for agents
- **Full documentation text**: https://docs.pre.dev/llms-full.txt — complete reference for full-text ingestion
- **OpenAPI schema**: https://docs.pre.dev/api-reference/openapi.json — REST methods, paths, and response schemas
- **MCP tools reference**: https://docs.pre.dev/mcp/tools — tool parameters and return formats
- **Critical pages**:
  - [Coding Agent quickstart](https://docs.pre.dev/coding-agent/quickstart) — build your first project
  - [API overview](https://docs.pre.dev/api-reference/overview) — all REST endpoints and SDKs
  - [Browser Agents quickstart](https://docs.pre.dev/browser-agents/quickstart) — extract data and automate workflows
  - [Guide for agents](https://docs.pre.dev/for-agents) — field names, polling patterns, and integration boundaries
  - [Errors and retries](https://docs.pre.dev/api-reference/errors) — HTTP codes, browser gate codes, and safe retry patterns

---

> For additional documentation and navigation, see: https://docs.pre.dev/llms.txt