spec-first

A discipline skill for LLM coding agents that enforces spec-derived, not probe-derived integration code.

Production-bound contract code is derived from a machine-readable spec committed in the repo. Probing is evidence, never source of truth.

What this skill does

When your LLM agent is implementing or modifying any code that touches a contract — vendor APIs, customer-facing endpoints, webhooks, queue payloads, or anything covered by an OpenAPI / GraphQL SDL / proto / JSON-Schema / RFC — this skill makes the agent:

1. Acquire the machine-readable spec before writing client/server code (with explicit fallback paths for HTML-only, PDF-only, and partial specs).
2. Commit the spec into the repo and write a one-page contract digest.
3. Derive code from the spec, not from probing or doc-page guessing.
4. Add a Spec citation: line to every contract-touching PR.
5. Lock URLs and required-field allowlists into tests so future drift fails CI.
6. Treat doc-vs-runtime divergences as tickets to file, not bugs to silently work around.
7. Refuse to ship probe-derived code under sunk-cost, time-pressure, authority, or fatigue rationalizations — the skill carries an explicit "no exceptions" clause and a 30-row red-flags table that pins every common rationalization with a specific counter.

When to use

Trigger this skill on any agent turn that involves:

• Writing or modifying client code that talks to an external API (vendor or customer-published).
• Implementing or modifying a server-side endpoint that exposes a contract to consumers (REST, GraphQL, webhook, queue payload).
• Adding or changing payload fields, headers, URL constants, status codes, or response-shape parsing.
• Implementing a new feature where a published spec, RFC, or standard exists.
• Anywhere a documented contract is the source of truth and probing/guessing would otherwise be tempting.

Install

Claude Code (CLI)

Drop the skill into your personal skills directory:

git clone https://github.com/<org>/<repo>.git /tmp/spec-first-skill
mkdir -p ~/.claude/skills
cp -r /tmp/spec-first-skill/spec-first ~/.claude/skills/

Restart your Claude Code session. The skill becomes discoverable to the model whenever a conversation matches its description.

Codex CLI

git clone https://github.com/<org>/<repo>.git /tmp/spec-first-skill
mkdir -p ~/.agents/skills
cp -r /tmp/spec-first-skill/spec-first ~/.agents/skills/

Paperclip (company-level skill library)

Import the skill into your company library and assign it to the agents who write integration code:

# Install at company level
curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/import" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "https://github.com/<org>/<repo>"}'

# Assign to a specific agent (e.g. your engineer or QA)
curl -sS -X POST "$PAPERCLIP_API_URL/api/agents/<agent-id>/skills/sync" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"desiredSkills": [..., "<org>/<repo>/spec-first"]}'

desiredSkills replaces the agent's full set on each call — fetch the current skills first and append spec-first rather than overwriting.

Gemini CLI

Skills load via Gemini's activate_skill flow. Place the skill directory where Gemini picks them up (per your platform docs) and reference it by name when prompting integration tasks.

Other platforms

Any LLM harness that supports Markdown-based skill files with YAML frontmatter (name, description) can ingest spec-first/SKILL.md directly.

What's in this repo

spec-first-skill/
├── README.md              ← this file
├── LICENSE                ← Apache-2.0
├── spec-first/
│   └── SKILL.md           ← the skill itself (entry point)
└── examples/
    ├── inbound-rest.md    ← walkthrough: vendor REST API w/ OpenAPI spec
    ├── outbound-webhook.md ← walkthrough: publishing a JSON-Schema'd webhook
    ├── graphql-divergence.md ← walkthrough: doc-page vs SDL conflict
    └── pdf-only-vendor.md  ← walkthrough: PDF-only contract + transcribed digest

How the skill was tested

The skill was authored using RED-GREEN-REFACTOR for skills (test-driven documentation):

1. RED — Three pressure scenarios run against a baseline LLM agent without the skill loaded. Captured verbatim rationalizations (sunk cost, probe-as-progress, "we control the outbound shape", etc.).
2. GREEN — Same scenarios re-run with the skill loaded. The agent must comply: delete sunk-cost code, refuse probe-derived shipping, write the JSON-Schema for outbound payloads, quote the red flag overruling each instinct.
3. REFACTOR — Two combined-pressure follow-ups (PDF-only vendor + authority + sunk-cost; incomplete-spec + sprint-end + fatigue + prior-precedent) surfaced 14 additional rationalizations now pinned in the red-flags table — including the self-citation trap and the partial-spec patching workflow.

Replicate this against any LLM agent before deploying the skill in your environment. The fixtures live in examples/.

Why this skill exists

A real-world incident catalogued in the skill's "Real-world impact" section: an integration with a freight booking vendor passed all mocked CI tests against the wrong URL because the test asserted request.url == VENDOR_URL_CONSTANT rather than the literal path. The constant had drifted; the URL no longer existed on the vendor's server; staging broke. The vendor's OpenAPI JSON, which would have made the URL self-evident, sat one URL away — an entire morning was burned guessing field names instead.

The skill encodes the rule that prevents this: the spec is the contract; the test asserts the literal; probes are evidence, not source of truth.

License

Apache License 2.0 — see LICENSE.

Contributing

The skill is amended via PR + changelog, not via Slack or chat messages. The "How the policy changes" section of the skill itself documents this. Changes that broaden or narrow trigger conditions should re-run the RED-GREEN-REFACTOR cycle to confirm the skill still resists the original rationalizations.