The Death of the Spec Doc — High Peak Studio

The product spec doc died the day your first agent shipped code before your kickoff meeting ended. In an agentic workflow, static prose is lagging indicator, not a source of truth. The teams that keep writing 12-page PRDs will be outrun by teams who ship executable intent.

Why the spec doc worked — and why it fails with agents

Specs were built for human-to-human coordination. You’re aligning people’s mental models, teasing out edge cases, and creating a compliance paper trail. In waterfall or even human-centric agile, the PRD, tech spec, and design doc made sense. They reduced ambiguity at human time scales: days, weeks, months.

Agent time is different. Agents operate at sub-hour cycles, remix context on the fly, and push changes in minutes. By the time you finish a spec review, the environment, data, or model has shifted. Your well-argued paragraph is now a lie told confidently.

The second failure is epistemic. Prose is imprecise for machines. Agents don’t “understand” a paragraph about pagination the way a human does. They need contracts, tests, and examples. Describe behavior as prompts, APIs, and checks, and you’ll get convergence. Describe behavior as prose, and you’ll get vibes and variance.

Finally, the spec locks you into decision debt. A PRD front-loads uncertainty resolution before you’ve run any experiments. With agents, the cheapest way to reduce uncertainty is to run the thing under guardrails and learn. You need a workflow that prioritizes testable intent over debatable intention.

Thesis: Replace design prose with machine-readable protocols and continuously verifiable intent. Ship governance and alignment as code, not paragraphs.

From documents to protocols: the PACT Stack

We use a named model at High Peak Studio for agentic delivery: the PACT Stack. It replaces the monolithic spec with four executable layers:

Prompts: the distilled intent and constraints agents use to act.
APIs: the interfaces, schemas, and tools agents can call.
Checks: acceptance tests, guardrails, and evaluators that define “done.”
Telemetry: the signals that make performance and drift visible.

A traditional spec tries to combine all of this in narrative form. The PACT Stack turns it into code and contracts that can be linted, executed, and audited. It deals with what agents need (structured, executable context) and what humans need (confidence, traceability, and alignment).

Prompts: distilling intent, not dictating steps

Agents need sharp objectives and constraints, not play-by-play instructions. A spec that lists “ask the database for X, then do Y” is brittle; an agent brief that states “maximize relevance subject to P0 safety checks” is resilient. We encode prompts as composable “briefs” with system messages, persona constraints, and a few canonical examples (golden records). They live in version control, get reviewed in pull requests, and have unit tests.

Pattern: Mission Brief. A concise artifact (200-500 words) stating goals, non-goals, constraints, and tone. One primary positive example and one near-miss negative example are required.
Pattern: Style Pack. A reusable package for brand voice, domain-specific tokens, and taboo terms to avoid. Agents import it like a library.
Pattern: Critic-Builder Loop. A pair of prompts: one that creates, one that critiques. The critic enforces Checks in natural language before formal tests run.

This is not “prompt engineering cosplay.” It’s executable intent. A Mission Brief that fails a test is a bug, not a debate.

APIs: narrow tools, stable contracts

In a spec, interfaces are an appendix. In agentic delivery, interfaces are the job. Agents perform best with narrow, well-labeled tools that expose pre-chewed capabilities. Give them a kitchen drawer of knives, not a junk pile of raw syscalls.

Pattern: Interface-First Swarm. Before building capabilities, define the set of tools with OpenAPI and JSON Schema. The system agent can only call these tools. If it can’t do the job, you need a new tool, not a new paragraph.
Pattern: Tool Linting. Each tool function ships with an example payload and a “what not to do” payload the evaluator can catch.
Pattern: Topology File. A DAG or YAML describing which agents exist, their roles, and allowed tool scopes. This replaces the team org chart portion of a spec.

APIs shrink context and reduce hallucination surface area. They also give you a place to put access control, quotas, and audit tags—things that prose specs waved at but couldn’t enforce.

Checks: define done with evaluators and tests

A spec’s acceptance criteria are prose checklists. In the PACT Stack, Checks are executable. We use three layers:

Deterministic tests: unit and integration tests against tools and pipelines.
LLM-as-judge evaluators: scoring rubrics that assess quality (clarity, safety, tone) on synthetic and real samples.
Red-team probes: adversarial prompts that try to break rules or cause regressions.

Agents run with a chaperone evaluator in the loop on P0 surfaces. If a run fails an evaluator threshold, it’s auto-escalated to a human or rolled back. “Shipped” means green checks, not green comments in a doc.

Telemetry: measure autonomy and drift

Specs age quietly. Telemetry screams. We track:

Intervention rate (percentage of runs needing human override).
Autonomy ratio (tool calls per escalation).
Outcome success (e.g., conversion lift, resolution time).
Prompt drift (distance from golden baselines).
Guardrail violations (severity-weighted count per 1k runs).

This is why the stack ends in Telemetry, not “Sign-off.” In an agentic world, discovery never stops; observability replaces ceremony.

The artifact set that replaces the spec

If you need an artifact list to share with your board or your compliance team, here’s what actually ships instead of a 12-page PRD. These are small, composable, and executable.

Mission Brief (1-2 pages): Objectives, non-objectives, constraints, tone, two canonical examples.
Topology File (YAML): Agents, roles, allowed tools, escalation rules.
Interface Contracts (OpenAPI/JSON Schema): Tool surface area with examples and anti-examples.
Acceptance Suite (tests + evaluators): Deterministic tests and LLM-judge rubrics with scoring thresholds.
Data Diet (documented datasets): Exactly what data the system can and cannot read, with PII boundaries.
Runbook (executable): Incident scripts, rollback toggles, feature flags; ideally infrastructure-as-code.
Golden Set (fixtures): Curated real-world examples that represent success and failure modes.
Telemetry Dashboard: Live metrics for autonomy, drift, outcomes, and guardrail violations.

Mission Brief vs PRD

A PRD tries to be comprehensive. A Mission Brief is intentionally incomplete on the “how,” and exhaustive on the “why” and “no-go” zones. It is testable by design: every sentence maps to a constraint, evaluator, or metric. Humans read it; agents are steered by its distilled prompts and examples.

Interface-first development

Don’t let a sprint start without an Interface Contract PR. The first commit in a new agentic service is schemas and tools, not model calls. If your team can’t articulate the tools and their example payloads, the problem is not spec clarity—it’s intent ambiguity.

Test-first acceptance

Before a single agent runs, ship a failing acceptance suite. It forces the conversation into “what must be true” rather than “what we might build.” This also shrinks rats nests of edge cases. If it’s not expressible as a test or evaluator, you probably don’t need it this sprint.

Three concrete examples

Example 1: Northloop Logistics Rate Optimizer

Northloop runs a regional freight service. They wanted an AI to rebid lane rates based on live capacity, historical win rates, and competitor chatter. The old-world approach would be a 20-page spec, a three-month build, and a pilot that misses peak season.

We used the PACT Stack and shipped a working optimizer in 10 days:

Prompts: A Mission Brief that stated “maximize expected margin subject to a 90% on-time SLA and ban any bids that undercut our cost floor.” Golden examples included a borderline holiday-week surge and a rainy-week disruption scenario.
APIs: Tools for “get_lane_history,” “query_capacity,” “simulate_bid,” and “submit_bid,” each with JSON Schemas and example payloads. No direct SQL—agents could only use these tools.
Checks: Deterministic tests for cost floors and SLA thresholds. An LLM-judge that scored rationales for verifiability (“cite at least two tools you called”) and compliance (“no rates with negative expected contribution margin”).
Telemetry: Autonomy ratio, margin delta versus control, and violation counts on floors.

Result: by day 3 the system bid in a sandbox. By day 7 we ran shadow mode against human raters. By day 10 we had a 2.3% margin lift with a 4% reduction in missed pickups, with a human-in-the-loop threshold for any lane with less than 20 historical instances. The “spec” wasn’t a doc; it was a dashboard, tests, and a Mission Brief PR.

Example 2: Pinstripe Talent Sourcer

Pinstripe is a boutique recruiting firm choking on inbound applicants. They needed an agent that could classify candidates, extract hard signals from noisy resumes, and write outreach that matched brand voice. The founder wanted a “tight spec” to protect the brand.

We gave her something better:

Prompts: A Style Pack encoding Pinstripe’s tone (“human, candid, never cute”), plus a Mission Brief with three canonical outreach examples and two strict taboo terms.
APIs: Tools to parse resumes, lookup ATS history, and generate outreach emails with a system-enforced token budget. A “send_email” tool was gated by a Check threshold score.
Checks: An evaluator scoring for tone adherence, factual correctness of extracted skills (verified against ATS), and prohibited phrases. A red-team probe tried to inject false skills via resume bullet weirdness.
Telemetry: Outreach reply rates by cohort, evaluator scores over time, and drift from Golden Set.

Pinstripe’s founder stopped asking for paragraphs about “what we will say.” She looked at live examples in a Golden Set, saw evaluator scores, and toggled thresholds. The brand was safer than with humans writing freestyle. They 3x’d recruiter throughput and raised reply rates by 18%.

Example 3: CedarPay Disputes Portal

CedarPay processes healthcare payments and needed an agentic disputes flow for patients contesting charges. Highly regulated, PHI everywhere, auditors in the loop. They came with a 27-page spec they’d used to brief a previous vendor who stalled for six months.

We did not throw out governance; we codified it:

Prompts: Mission Brief with explicit PHI handling rules and empathy guidelines. Golden examples included edge cases (deceased patient, minor guardianship) with expected outcomes.
APIs: Tools with strict scopes—“get_statement,” “request_medical_record,” “post_dispute_hold,” all instrumented with access tags and delay budgets. No tool could run without an audit context ID.
Checks: Deterministic HIPAA flags on payloads, PII redaction checks, and an evaluator for empathy (“acknowledge hardship,” “avoid blame”). Red-team prompts tested data exfiltration attempts.
Telemetry: Escalation rate, average time-to-resolution, and severity-weighted guardrail violations. A separate auditor dashboard streamed an immutable log of tool calls by context ID.

We shipped an MVP in four weeks. Auditor sign-off took hours, not weeks, because the governance was live and executable. CedarPay retired the 27-pager and now approves changes via PRs to Checks and Tools.

Vibe coding, on purpose

“Vibe coding” sounds like chaos. At High Peak, it’s a discipline: the craft of encoding product feel into prompts, examples, and evaluators so agents can produce brand-right outcomes by default. You do it intentionally, not by intuition.

Here’s how we operationalize it:

Style Packs define tone, taboo terms, preferred sentence structures, and sample microwins (microcopy bits that feel right). They ship as versioned prompt fragments with tests that check tone adherence on synthetic prompts.
Scenario Libraries collect 20-50 realistic user intents annotated with “desired vibe.” These become Golden Sets for evaluators to score.
Evaluator Ensembles include a “Brand Critic” and a “Fact Checker.” The Brand Critic scores voice and empathy; the Fact Checker scores citations and claims. The combined score gates autonomy.

When people say “we need the spec to ensure quality,” they’re usually masking vibe anxiety. Use vibe coding to bring the feel from the heads of your best PMs and writers into artifacts agents can consume and you can measure.

Counter-arguments and failure modes

Every founder who loves specs has good reasons. Specs feel like control. They tell a story that makes the future legible. So let’s acknowledge the strongest counterpoints and show where they’re valid—and where they’re leading you into a ditch.

“We need specs for compliance and audits”

Yes, you need traceability. But prose is the worst compliance artifact because it’s not enforceable. Auditors want to know what the system does under conditions X and Y, not what you hoped it would do. Give them interface contracts, evaluator thresholds, and immutable logs of tool calls keyed by request ID.

In regulated cases, keep a short Policy Brief that maps regulations to Checks and Tools. One page, max. You’ll pass audits faster because you’re aligning to testable reality, not to fiction. CedarPay’s auditor took 45 minutes to bless what used to take 3-4 weeks—the difference was executable governance.

“Without a spec, stakeholders go rogue”

Stakeholders go rogue when they don’t see where decisions live. The PACT Stack puts decisions in PRs and dashboards. If marketing wants a different tone, they propose a Style Pack change. If sales wants a new flow, they propose a Tool addition and a new evaluator score threshold.

We’ve seen fewer cross-functional blowups after killing the PRD. People argue on the object—the test or the tool—not on abstractions. You can ship a “preview” branch that stakeholders can play in and see the change in minutes.

“Specs prevent rework”

Specs prevent a specific kind of rework: the human kind that comes from misread paragraphs. They do nothing for rework caused by new data, drifting models, or unseen edge cases. In agent land, rework is minimized by shortening the learn loop, not by up-front prose.

The antidote to rework is strong Checks and cheap rollbacks. If a change goes sideways, your Runbook toggles a feature flag, Telemetry tells you why, and you iterate on the evaluator rubric—fast. Rework becomes just another run.

Failure modes in agentic workflows

Prompt sprawl: dozens of ad hoc prompts floating in tools. Fix by centralizing Style Packs and Mission Briefs with ownership and tests.
Zombie agents: agents nobody uses but which still run and cost money. Fix by enforcing Autonomy Ratio and deprecating agents that fail value thresholds.
Interface rot: undocumented tool changes break behavior. Fix by treating Interface Contracts as code with semver, changelogs, and regression tests.
Evaluator overfitting: teams game the LLM-judge instead of improving outcomes. Fix with spot checks, blind human ratings, and outcome metrics in Telemetry.

None of these are solved by a spec doc. All of them are solved by operational ownership and the PACT Stack.

Adopting agentic delivery: org shift, tooling, and metrics

Killing the spec doesn’t mean killing alignment. It means moving alignment into code and telemetry, and instituting a cadence that feels like engineering, not committee. Here’s the practical path.

Org shift: roles and rituals

Responsible: Product Engineering owns the PACT Stack; a named “Agent Lead” per surface area is accountable for Prompts and Checks.
Consulted: Compliance, brand, and data owners review Mission Briefs, Style Packs, and Data Diets through PRs with bound SLAs (48 hours max).
Informed: Executives consume one Telemetry dashboard and a weekly change digest of PACT diffs.

Rituals change too:

Monday: ship failing acceptance tests for the week’s goals; PRs for Interface Contracts.
Midweek: shadow mode runs and evaluator tuning.
Friday: demo from live branch; merge if Checks pass and Autonomy Ratio meets threshold.

This cadence replaces “spec review” with “artifact review.” You’ll find misalignments earlier because they show up as red tests and off-metric telemetry, not as heated narrative debates.

Tooling you actually need

Version control for prompts, evaluators, and schemas. Use Git like you mean it. Treat prompts as code.
Schema-first interfaces via OpenAPI/JSON Schema. Generate tool stubs and validators.
Evaluator harness to run LLM-as-judge with rubrics. Record scores, samples, and explanations.
Experiment registry for model variants, prompts, and dataset snapshots. Label and replay runs.
Observability pipeline that logs tool calls with context IDs, traces latency, and emits guardrail violations.
Feature flags and rollback toggles wired to your Runbook and Telemetry.

Buy or build, but do not fake these. You can glue them with a light orchestrator that supports agent topologies, tool injection, and evaluator hooks. The rest is ceremony and cost.

Metrics that matter

DORA metrics don’t translate 1:1. In agentic delivery, watch:

Intent-to-Ship Latency: time from Mission Brief PR to passing acceptance suite.
Intervention Rate: percentage of runs with human overrides.
Autonomy Ratio: tool calls per escalation; rising equals maturing.
Evaluator Pass Rate: distribution of LLM-judge scores; track 50th and 90th percentiles.
Outcome Delta: business KPI change vs. control (margin, CSAT, reply rate).
Drift Index: divergence from Golden Set over time; spikes trigger review.

If a team can’t show these, they’re flying by vibes. If they can, you’ve got a live spec—that’s the point.

What about planning, estimation, and funding?

Specs historically served as planning collateral. In agentic work, estimation revolves around uncertainty buckets and test readiness, not pages written. Your board doesn’t want fiction; they want clear gates and observed progress.

Plan by uncertainty reduction: identify the riskiest unknowns and instrument acceptance tests that would close them. Budget sprints to kill the top 1-2 unknowns, not to write prose.
Estimate by artifact maturity: a week where Interface Contracts and failing tests exist is 70% of the way to a demo. A week of “we wrote a spec” is 0% of the way to anything.
Fund by metric milestones: unlock spend when Intervention Rate drops below a threshold and Outcome Delta crosses a line. That’s a gate a CFO can love.

Planning slides now point to artifacts and telemetry, not paragraphs. It’s more honest. It’s also faster.

How to apply this tomorrow

If you want to try this without boiling the ocean, here’s a practical, minimal pass. You can implement it in a week with a small team.

Pick a thin slice: choose one surface (e.g., support email replies) where agents can act with low blast radius. Avoid core billing day one.
Write a Mission Brief: two pages max. Objectives, non-objectives, constraints, tone, one gold-positive example, one gold-negative. PR it; timebox review to 48 hours.
Define three tools: list the minimum actions the agent needs. Spec them with JSON Schemas and example payloads. No raw DB access.
Ship a failing acceptance suite: 3-5 deterministic tests and one LLM-judge rubric with pass thresholds. Include one red-team probe.
Stand up telemetry: log tool calls with context IDs and show Intervention Rate in a basic dashboard. Even a spreadsheet beat is fine on day one.
Run shadow mode: let the agent draft outcomes; humans approve. Tune evaluators until pass rate stabilizes and Intervention Rate trends down.
Enable limited autonomy: set strict thresholds and feature flag the agent for a subset (e.g., 10% of traffic, low-risk segments).
Iterate weekly: adjust tools and evaluators in PRs. Retire any prompt sprawl; centralize into Style Packs.
Retrospect on metrics: review Autonomy Ratio, Outcome Delta, and Drift Index. Promote or roll back based on numbers, not narratives.
Codify governance: if regulated, add a one-page Policy Brief that maps regs to Checks and Tool scopes. Link it in your auditor dashboard.

This is the skeleton. You’ll notice there is no “spec review.” There is review—of artifacts and tests. Your calendar gets lighter; your product gets tighter.

Bottom line

Specs were built for human time scales; agents operate at machine time. Replace prose with the PACT Stack—Prompts, APIs, Checks, Telemetry—and govern with code and metrics. You’ll move faster, align better, and ship with less drama and more truth.