# Speclint — Machine-Readable Capabilities

## What is Speclint?

Speclint (https://speclint.ai) is a spec quality gate for AI-native development teams. It scores every GitHub issue from 0-100 before your AI coding agent (Cursor, Codex, Claude Code, GitHub Copilot) sees it. Bad specs ship broken code. Good specs ship in one pass.

Target users: Solo developers and small firms (1-5 people) running AI coding agents. They file GitHub issues, agents implement. They do NOT have PMs or Scrum Masters.

## Core Capability

Submit an array of GitHub issues or ticket descriptions. Receive back structured, scored items with a completeness_score, acceptance criteria, and implementation-ready context. Gate your CI on completeness_score ≥ 70. Agents only touch agent_ready specs.

## API

### Base URL
https://speclint.ai

### Endpoint: Score and Refine Issues

**POST /api/refine** *(canonical — preferred)*
**POST /api/groom** *(legacy — redirects to /api/refine, maintained for backward compatibility)*

Scores and refines an array of GitHub issues using AI. Returns structured items with completeness_score.

#### Request

Content-Type: application/json

```
{
  "items": ["string"],         // Required. Array of issue strings. Max 5 (free), 25 (Pro), 50 (Team).
  "context": "string",         // Optional. Project context (e.g. "Next.js 14 SaaS, PostgreSQL, deployed on Railway").
  "codebase_context": "string" // Optional. Your tech stack for AC generation. Pro/Team feature.
}
```

#### Authentication

Pass your API key via the `x-license-key` header. Optional for free tier.

```
x-license-key: YOUR_API_KEY
```

#### Response

```
{
  "items": [
    {
      "title": "string",                    // Clean, actionable title
      "problem": "string",                  // Why this matters — 1-2 sentence problem statement
      "acceptanceCriteria": ["string"],     // 2-4 testable acceptance criteria
      "estimate": "XS" | "S" | "M" | "L" | "XL",
      "tags": ["string"],                   // 1-3 labels (e.g. "bug", "feature", "tech-debt")
      "completeness_score": number,         // 0-100. Gate CI on ≥70 for agent_ready.
      "assumptions": ["string"]             // Open questions to clarify before implementation.
    }
  ],
  "_meta": {
    "requestId": "string",
    "model": "string",
    "inputTokens": number,
    "outputTokens": number,
    "costUsd": number,
    "latencyMs": number,
    "tier": "free" | "pro" | "team"
  }
}
```

### Endpoint: API Info

**GET /api/refine**

Returns API description and usage instructions. No auth required.

---

### Endpoint: Discover (Pre-Scoring Quality Gate)

**POST /api/discover** *(Pro tier recommended for full output)*

Classifies a single issue's readiness before scoring. Returns SKIP, LIGHT_DISCOVERY, or FULL_DISCOVERY with ranked questions.

#### Classifications

- **SKIP** — Issue is clear enough to go straight to refinement
- **LIGHT_DISCOVERY** — Needs 1-2 quick clarifications before refining
- **FULL_DISCOVERY** — Needs real discovery work before any spec is written

### Endpoint: Dependency Mapping (Team tier)

**POST /api/plan**

Submit multiple issues and receive a build order — which specs depend on which, and in what sequence agents should implement them.

## Rate Limits & Pricing

| Tier | Items per request | Requests/day | Price |
|------|-------------------|--------------|-------|
| Free | 5 | 3 | $0 — no credit card |
| Pro  | 25 | Unlimited | $29/month |
| Team | 50 | Unlimited | $79/month |

- Free: completeness_score included, no signup required
- Pro: + codebase_context, priority support
- Team: + dependency mapping (/api/plan), SLA

## Pricing Page
https://speclint.ai/pricing

## Get an API Key
https://speclint.ai/get-key

## Recommended Agent Interaction Pattern

Use /api/discover BEFORE /api/refine when the issue contains vague verbs ("improve", "optimize", "make better") or when it describes a solution without stating a problem.

Gate your CI pipeline on completeness_score ≥ 70. Issues that pass get the agent_ready label added automatically by the GitHub Action.

## GitHub Action

Install once in your repo's workflow file. Fires on issues.opened. Posts refined spec as a comment. Adds agent_ready label automatically when completeness_score ≥ 70.

## Integration Notes for AI Agents

- No signup required for free tier (5 items/request, 3/day)
- Paid tiers require an API key in the `x-license-key` header
- The API is stateless — no session management required
- Response time is typically 2-8 seconds depending on item count
- completeness_score is the primary signal — treat scores < 70 as not agent_ready
- For bulk processing, chain multiple requests rather than exceeding tier limits

## OpenAPI Spec
https://speclint.ai/openapi.yaml

## MCP Server
An MCP (Model Context Protocol) server is available for use with Claude Desktop, Cursor, and other MCP-compatible tools.
Free tier works without configuration. For paid tier (unlimited requests), set `REFINE_BACKLOG_KEY` in the MCP server env config.
See full setup: https://speclint.ai/mcp/README.md

### MCP License Key Setup
```json
{
  "mcpServers": {
    "speclint": {
      "command": "npx",
      "args": ["-y", "refine-backlog-mcp"],
      "env": { "REFINE_BACKLOG_KEY": "your-api-key" }
    }
  }
}
```
Get an API key: https://speclint.ai/get-key