Speccify

Playbooks for coding agents

You have done this before. Write it down once.

A playbook captures a complex, recurring workflow — the ordered steps, the sources they came from, the assets they need, and the pitfalls you only find out about once. It is written for coding agents, versioned, pinned by hash, and checked for rot. Shared like Go modules over Git — no account, no central registry, all MIT.

Quickstart Mac app GitHub

The problem

  • · The same intricate task — notarizing an app, wiring up a trial purchase, a migration — is researched from scratch every time it comes up.
  • · What you learned the hard way ends up in a scratch file, a closed ticket, or nowhere. It is not there the next time.
  • · Agents are good at writing the code and bad at knowing the fine print: which order, which flag, which step Apple silently requires.

The idea

  • · One versioned playbook holds the steps, the sources each one came from, and the assets it needs — the whole workflow, not a summary of it.
  • · speccify check reports how old every source is and whether its URL still resolves. Instructions that quietly went stale are worse than none.
  • · Agents read playbooks directly over MCP — find one, read a step, fetch an asset. No copy-paste from a wiki.

What a step looks like

From the in-app-purchase playbook in this repository. A step says what to do, what it was learned from, and how you know it worked. 

steps:
  - id: trial_storage
    title: Store the start date where deleting the app cannot reach
    detail: |
      UserDefaults survives a backup but not a delete; the Keychain
      survives a delete but not a new device. Write to both, read
      the union, earliest start wins.
    sources: [review_guidelines]
    verify: Deleting and reinstalling does not reset the days left.

Worth writing down

The test is not how big a task is. It is: would I have had to look this up again the second time?

Platform rituals

Notarization, entitlements, store review

Payments & auth

Trials, subscriptions, OAuth flows

Migrations

Version bumps with an order that matters

Release & ops

Signing, rollout, rollback

Find it, pin it, check it

$ speccify search notarization
Notarize a Tauri app for macOS  [macos, tauri]
  git+https://github.com/speccify/playbooks#macos-notarize-tauri

$ speccify add git+https://github.com/speccify/playbooks#macos-notarize-tauri
✓ resolved  v1.0.0 → commit 9f1c0b1
✓ pinned    speccify.lock

$ speccify check playbooks/ --links
warning  $.sources[2]  last retrieved 214 days ago — re-read it

How it works

1 · Write it once

The second time you do something, write it down: steps, the sources you actually read, the assets you needed.

2 · Tag it

Publishing is git tag and git push. The repository URL is the identity, tags are the versions. No account, no registry.

3 · Pin it

speccify.lock pins each playbook by a hash over its whole bundle and, for git sources, by commit. What you used still says the same thing.

4 · Hand it to an agent

Over MCP the agent reads the steps and assets itself — and speccify check tells you when a source has gone stale.

Read it with an agent beside you

The viewer shows the workflow as a diagram, the steps as rendered markdown, every source with its age. There is no edit mode: you select a step and ask the agent next to it, which reads that selection through MCP. When the answer belongs in the playbook, it proposes the change and you see a diff. Nothing is written until you click Apply.

Get started