# MCP Factory Pre-Flight & Post-Flight Checklist

> **THIS IS MANDATORY. Read this BEFORE every factory spawn. No exceptions.**
> Last updated: 2026-02-14

---

## PRE-SPAWN CHECKLIST (before spawning ANY build agent)

### 1. API Spec First
- [ ] Downloaded or located the official OpenAPI/Swagger spec
- [ ] If no spec: systematically crawled API docs and built endpoint inventory
- [ ] Total endpoint count documented
- [ ] Endpoint inventory saved to `{server}/API_INVENTORY.md`

### 2. Workflow Mapping
- [ ] Researched top 5-10 real user workflows for this platform
- [ ] Tiered tools: Tier 1 (daily), Tier 2 (power user), Tier 3 (completionist)
- [ ] Minimum tool target set based on API size:
  - Small API (<30 endpoints): 15-20 tools
  - Medium API (30-100 endpoints): 30-50 tools
  - Large API (100+ endpoints): 50-80+ tools

### 3. Agent Isolation
- [ ] Each agent gets its OWN workspace directory (NOT shared with other agents)
- [ ] Directory path: `workspace/{server-name}-build/` (NOT directly in mcpengine-repo)
- [ ] Merge to mcpengine-repo ONLY after verification passes

### 4. Agent Instructions
- [ ] Single-purpose task (tools only, apps only, or fixes only — NOT "build everything")
- [ ] NO "delete everything first" language anywhere in the prompt
- [ ] Timeout set correctly:
  - Tools only: 600s (10min)
  - Apps only: 600s (10min)
  - Full server build: 900s (15min)
  - Fix/patch jobs: 300s (5min)
- [ ] Naming conventions included in prompt (snake_case, list_/get_/create_/update_/delete_/search_)
- [ ] Rich description requirements included ("tell an AI agent WHEN to use this tool")
- [ ] Pagination/rate limit handling requirements included

### 5. No Competing Agents
- [ ] Checked: no cron jobs that might spawn agents for the same server
- [ ] Checked: no other manual agents running on the same server
- [ ] One coordinator, one set of workers — no freelancers

---

## POST-COMPLETION CHECKLIST (after EVERY agent returns)

### 1. Filesystem Verification (NEVER trust the narrative)
```bash
# Run these BEFORE believing anything the agent said:
SERVER="{server-name}"
DIR="workspace/${SERVER}-build"

# Count actual files
echo "=== Tool files ==="
find "$DIR/src/tools" -name "*.ts" 2>/dev/null | wc -l

echo "=== App files ==="
find "$DIR/src/apps" -name "*.ts" -o -name "*.tsx" -o -name "*.html" 2>/dev/null | wc -l

echo "=== Type files ==="
find "$DIR/src/types" -name "*.ts" 2>/dev/null | wc -l

echo "=== Total .ts files ==="
find "$DIR/src" -name "*.ts" 2>/dev/null | wc -l

echo "=== Server entry ==="
ls -la "$DIR/src/index.ts" 2>/dev/null || echo "MISSING"

echo "=== README ==="
ls -la "$DIR/README.md" 2>/dev/null || echo "MISSING"
```

### 2. Quality Checks
- [ ] Tool count matches or exceeds minimum target
- [ ] Tool descriptions are rich (not just "Lists X" — includes when/why/params)
- [ ] `_meta` labels present on tools (category, access, complexity)
- [ ] Pagination handled in list_* tools (cursor/page support, has_more indicator)
- [ ] Error handling present (not just raw API throws)
- [ ] Naming conventions followed (no mixed fetch_/get_/retrieve_)

### 3. Coverage Manifest
- [ ] README contains coverage table:
  ```
  Total API endpoints: X
  Tools implemented: Y
  Intentionally skipped: Z (with reasons)
  Coverage: Y/X = NN%
  ```

### 4. Compile Check
```bash
cd "$DIR" && npx tsc --noEmit
```

### 5. Commit & Merge
- [ ] Only after ALL above checks pass
- [ ] Copy to mcpengine-repo: `rsync -a --exclude='node_modules' --exclude='.git' "$DIR/" "mcpengine-repo/servers/${SERVER}/"`
- [ ] `cd mcpengine-repo && git add -A && git commit -m "${SERVER}: {summary}" && git push`
- [ ] Verify push succeeded

---

## EMERGENCY RECOVERY
If an agent wipes files that were already committed:
```bash
cd mcpengine-repo && git checkout HEAD -- servers/{server-name}/
```

---

## AGENT PROMPT TEMPLATE
Use this as the BASE for all factory agent prompts:

```
You are building the {PLATFORM} MCP server.

WORKSPACE: Write ALL files to /Users/jakeshore/.clawdbot/workspace/{server-name}-build/
DO NOT write to mcpengine-repo directly.
DO NOT delete any existing files.

API SPEC: {link or pasted spec}
ENDPOINT INVENTORY: {pasted or referenced}

YOUR TASK: {specific single-purpose task}

NAMING CONVENTIONS:
- list_* for paginated collections
- get_* for single resource by ID  
- create_*, update_*, delete_* for mutations
- search_* for query-based lookups
- Domain verbs: send_email, cancel_event, archive_card, assign_task
- All snake_case, all lowercase

TOOL DESCRIPTIONS must tell an AI agent WHEN to use the tool:
- BAD: "Lists contacts"
- GOOD: "Lists contacts with optional filtering by email, name, tag, or date range. Use when the user wants to find, search, or browse their contact database. Returns paginated results up to 100 per page."

Every list_* tool must support pagination (cursor/page tokens, has_more indicator).
Every tool must have _meta labels: category, access (read/write/destructive), complexity.

COVERAGE TARGET: {minimum tool count} tools minimum.
```
