Spec-Driven AI Dev

What's in this pack

This pack collects the five spec-driven tools that make AI coding auditable. Each one tackles a different part of the spec → agent → review loop, and they compose well in a single project.

OpenSpec and Planning with Files are the load-bearing pair. OpenDeepWiki gives the agent the codebase context it needs to write a competent spec, and Rivet is the visual layer for teams that prefer node graphs over markdown.

Why spec-driven

"Vibe coding" — telling the agent what you want and hoping for the best — works for tiny tasks and falls apart on anything multi-day. Three problems compound:

• Drift. The agent loses track of intent across many turns. Each new turn re-derives goals from chat history, which is lossy.
• Audit. When the PR lands you cannot tell what the agent thought it was building. Reviewers reverse-engineer intent from code diffs.
• Branching. Three concurrent attempts at the same feature have no shared source of truth.

A spec fixes all three. Intent lives in a markdown file the agent reads on every turn (no drift). The diff between specs versions is the audit trail (no reverse-engineering). Concurrent attempts fork the spec the same way they fork code (clean branching).

Install in one command

# Install the entire pack
tokrepo install pack/spec-driven-ai-dev

# Or pick the core pair
tokrepo install openspec
tokrepo install planning-with-files

OpenSpec lands as a specs/ directory plus a Claude Code subagent that reads and updates it. Planning with Files installs a hook that prompts the agent to emit a PLAN.md before editing any code. OpenDeepWiki runs as a separate process that crawls your repo and serves a queryable wiki. Rivet is a desktop app and is installed via npm install -g @ironclad/rivet.

Common pitfalls

• Specs that are too coarse. "Build a checkout flow" is a goal, not a spec. A usable spec lists acceptance criteria, edge cases, and out-of-scope items. OpenSpec's template enforces this structure; resist the urge to delete the sections you find awkward.
• Specs that are too fine. A 500-line spec for a 20-line patch is over-engineering. Match spec depth to task risk: tiny patches get a one-paragraph spec, multi-week features get the full template.
• Spec rot. When the implementation diverges from the spec, the spec becomes a lie. The agent will follow the lie. Keep the spec live: every PR updates it or explicitly notes the deviation.
• Confusing planning files with specs. PLAN.md is the agent's reasoning trace for the next batch of work; the spec is the durable artifact. Don't conflate them; the planning file is throwaway.
• Rivet for everything. Rivet shines for branching prompt flows; it is overkill for single-shot coding tasks. Use it when the graph adds clarity, not as a default.

Relationship to other packs

• Anthropic Builders ships the agent runtime; this pack adds the spec layer on top.
• Prompt Engineering Toolkit sharpens the language used inside specs and plans.
• LLM Eval & Guardrails lets you assert that the agent's output matches the spec's acceptance criteria.

When this pack alone isn't enough

Spec-driven dev assumes you already know what you want. For exploratory work — "what should this product even be?" — start with a discovery process (interviews, prototypes, sketches), then translate findings into specs. Skipping that step yields beautifully-formatted specs for the wrong product. The pack is a force multiplier for clarity, not a substitute for it.

A second limit: specs do not replace tests. The spec describes intent and acceptance criteria in prose; tests verify those criteria mechanically. Most teams keep both — the spec for the human reviewer, the test for the CI machine — and let the agent author both during the same turn.