# 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/lint** *(canonical — preferred)*
**POST /api/refine** *(deprecated alias — still works, redirects to /api/lint)*
**POST /api/groom** *(legacy — redirects to /api/lint, 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

**Option A — Plain strings (items):**
```
{
  "items": ["string"],         // 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.
  "preserve_structure": false, // Optional. When true, each input string is scored as a single item without decomposition. Default: false.
  "persona": {                 // Optional. Target user persona for persona-aware scoring. Solo/Team feature.
    "role": "string",          //   e.g. "frontend developer at 3-person AI dev firm"
    "cares_about": ["string"], //   e.g. ["CI integration", "agent compatibility", "fast iteration"]
    "doesnt_care_about": ["string"] // e.g. ["enterprise compliance", "manual QA"]
  }
}
```

**Option B — Structured GitHub issues (issues):**
```
{
  "issues": [                  // Alternative to items. Pass structured GitHub issue objects.
    {
      "title": "string",       // Required. Issue title.
      "body": "string",        // Required. Issue body / description.
      "labels": ["string"]     // Optional. Issue labels (e.g. ["bug", "feature"]).
    }
  ],
  "context": "string",         // Optional. Same as above.
  "preserve_structure": false  // Optional. Same as above.
}
```

> **Note:** Send either `items` or `issues`, not both. Sending both returns HTTP 400.

#### 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/lint**

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 (Solo): + codebase_context, persona-aware scoring (persona_alignment + persona_gaps), priority support
- Team: + dependency mapping (/api/plan), SLA

### Persona-Aware Scoring (Solo/Team tiers)
Pass a `persona` object with your request to receive a `persona_alignment` score (0-100) for each item.
The score measures how well the spec addresses your user's concerns:
- 50 pts: concern_coverage — how many `cares_about` items are addressed in ACs/problem
- 25 pts: anti_concern_avoidance — spec does NOT focus on `doesnt_care_about` items
- 25 pts: role_appropriate_language — spec references context relevant to the persona's role
Each item also returns `persona_gaps`: which `cares_about` items are missing from the spec.
`agent_ready` is gated on BOTH completeness_score ≥ 70 AND persona_alignment ≥ 60 when persona is provided.
Free-tier requests with `persona` receive `upgrade_message` instead of scores.

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

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

## AI-Assisted Spec Rewrite (POST /api/rewrite)

When a spec scores below threshold, use /api/rewrite to get an AI-improved version in seconds.

Request body:
```json
{
  "spec": "Add search to dashboard",
  "gaps": ["has_measurable_outcome", "has_testable_criteria", "has_definition_of_done"],
  "score": 40
}
```

Pass the `x-license-key` header for Solo/Team tier access.

**Free tier**: Returns `preview` (first 100 chars) + `upgrade_message`. No `rewritten` field.
**Solo/Team tier**: Returns full `rewritten` spec, `changes` array, and `new_score` from re-lint.

The rewrite is a suggestion only — never auto-applied. Review before committing.

Recommended agent pattern: lint → if score < 70 → rewrite → review → commit.

## 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 `SPECLINT_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", "speclint-mcp"],
      "env": { "SPECLINT_KEY": "your-api-key" }
    }
  }
}
```
Get an API key: https://speclint.ai/get-key

## Lint Receipt Verification (SL-037)

Every lint response includes a `lint_id` field (format: `spl_` + 8 hex chars, e.g. `spl_a1b2c3d4`).

This ID is a verifiable receipt stored in Redis for 30 days. Use it to prove a spec was genuinely linted by Speclint — not fabricated by an intermediary agent.

### Verify a receipt:
```
GET https://speclint.ai/api/verify?id=spl_a1b2c3d4
```

Response:
```json
{
  "lint_id": "spl_a1b2c3d4",
  "score": 82,
  "breakdown": { "has_problem_statement": true, ... },
  "title": "Fix session timeout bug",
  "timestamp": "2026-03-01T14:42:00.000Z",
  "tier": "free",
  "agent_ready": true
}
```

- No authentication required — receipts are public
- Returns 404 if the receipt is expired (>30 days) or the ID is invalid
- `lint_id` appears in both the top-level response AND on each item object