Add mandatory MCP factory checklist + enforce in AGENTS.md
This commit is contained in:
Jake Shore
parent
00823fb44d
commit
9d5c7cc0e8
@ -82,12 +82,17 @@ This keeps identity, memory, and progress backed up. Consider making it private
|
||||
- End every reply with a model tag: `· sonnet` or `· opus`
|
||||
- This costs ~2 tokens, helps Jake track what's being used
|
||||
|
||||
## MCP Work — MANDATORY Commit Rule
|
||||
## MCP Work — MANDATORY Commit Rule + Factory Checklist
|
||||
|
||||
**ALL MCP-related work MUST be committed and pushed to `mcpengine-repo/` (`BusyBee3333/mcpengine`).**
|
||||
|
||||
This is non-negotiable. The mcpengine repo is the single source of truth.
|
||||
|
||||
### MANDATORY: Factory Checklist
|
||||
**Before spawning ANY MCP build agent:** Read `mcp-factory-checklist.md` and follow the pre-flight checklist.
|
||||
**After ANY agent completes:** Run the post-completion verification. NEVER trust agent narratives — verify the filesystem.
|
||||
**No exceptions. No shortcuts. Jake said so.**
|
||||
|
||||
### What goes where:
|
||||
- New MCP server → `mcpengine-repo/servers/{platform-name}/`
|
||||
- MCP apps/UI → `mcpengine-repo/servers/{platform-name}/src/apps/` or `ui/`
|
||||
|
||||
145
mcp-factory-checklist.md
Normal file
145
mcp-factory-checklist.md
Normal file
@ -0,0 +1,145 @@
|
||||
# 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.
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user