Spec-Driven Development with AI Agents: The Semantic Wiki Handoff Architecture

Spec-driven development (SDD) emerged in 2025 as the direct industry corrective to the pervasive failure modes of "vibe coding": autonomous agents generating syntactically valid code that steadily drifts from business intent, hallucinates non-existent APIs, and introduces silent regressions across long horizons.

By late 2026, the industry converged on a foundational principle: write down testable requirements, validate architecture decisions, establish verifiable task gates, and only then unleash coding agents — with the written specification, not the conversational chat scrollback, acting as the immutable source of truth.

However, in multi-repository small-business and enterprise ecosystems (such as the Simple Agility stack spanning stockroom, roller, jspwiki, and jakemon), conventional in-repo markdown specs create documentation silos and cross-service drift. Modern Level-5 agentic engineering elevates SDD from local repository text files to sovereign, semantic wiki handoff specifications queried directly by autonomous coding agents via the Model Context Protocol (MCP).

sequenceDiagram
    autonumber
    actor Human as Human Architect / Operator
    participant Arch as Architecture Agent (wiki-content-agent)
    participant Wiki as Wikantik Knowledge Plane (/knowledge-mcp)
    participant Eng as Core Engineering Agent (Claude Code / agy)
    participant Repo as Product Codebase (stockroom / roller)
    participant CI as Deterministic Verification Harness

    Human->>Arch: Strategic directive / feature vision
    Arch->>Arch: Formulates EARS requirements & data contracts
    Arch->>Wiki: Publishes Technical Handoff Spec & ADR (SA-11, SA-12)
    Note over Human,Wiki: Human Gate: Architect reviews spec, resolves open questions (/grill-me)
    Human->>Eng: Triggers implementation ("Implement SA-11 from Wikantik")
    Eng->>Wiki: Calls assemble_bundle / read_pages(SimpleAgilityCommerceDataFlow)
    Wiki-->>Eng: Injects immutable schemas, COA mappings, and DDL migrations
    Eng->>Repo: Executes Test-Driven Development (TDD) against spec
    Repo->>CI: Runs mutation testing, linters, and conformance gates
    CI-->>Eng: Passes all gates (0 test regressions)
    Eng->>Wiki: Stamps verification state (mark_page_verified)

1. Why Written Specifications Beat Conversational Prompts

A conversational prompt entered into an LLM chat window is consumed once and discarded. As the session progresses, it is vulnerable to context window eviction, lossy compaction, and conversational drift. A formal specification, by contrast, acts as an immutable external cognitive anchor:

  1. Upstream Defect Detection: Reviewing a structured 1,500-word specification takes five to ten minutes and catches fundamental architectural flaws (data model deadlocks, race conditions, missing foreign keys) before an agent writes 2,500 lines of brittle code.
  2. Persistence Across Compaction & Restarts: Long-horizon tasks require multi-hour runs that frequently exhaust context limits. An on-disk or wiki-hosted specification can be re-read cold at full fidelity whenever an agent re-anchors or hands off work to a secondary agent.
  3. Deterministic Verification Criteria: A specification structured with formal acceptance criteria converts subjective completion ("the agent thinks it's done") into automated, binary evaluation ("all 14 EARS test assertions pass").
  4. The Cold-Reader Litmus Test: If a fresh agent session initialized with zero conversational history cannot execute an implementation task solely by reading the specification, the plan was living in the engineer's head or chat scrollback, not in the specification.

2. The Artifact Hierarchy: Requirements, Design, and Tasks

Effective SDD organizes requirements across three distinct, reviewable stages:

flowchart LR
    REQ["1. Requirements<br/>(EARS syntax, non-goals)"]
    DES["2. Technical Design<br/>(Schemas, ADRs, trade-offs)"]
    TSK["3. Ordered Tasks<br/>(Atomic, test-gated work items)"]

    REQ --> DES --> TSK

Stage 1: Requirements via EARS Syntax

Requirements must be formulated as unambiguous, machine-parsable statements. The Easy Approach to Requirements Syntax (EARS) provides a standardized grammar that eliminates agent misinterpretation:

Stage 2: Technical Design

The design stage formalizes the "how": database schemas (Flyway SQL DDL), domain event models, API signatures, error handling matrices, and architectural trade-offs considered and rejected. This is where living Architecture Decision Records (ADRs) are bound (SimpleAgilityDecisionLog).

Stage 3: Atomic, Verifiable Tasks

Tasks decompose the design into ordered work items where each item possesses an independent verification gate:

  1. Task 1: Flyway migration V028__add_attribution_to_sale.sql (Verification: ./mvnw test -Dtest=FlywayMigrationTest)
  2. Task 2: EbayOrderLineMapper promotion parser (Verification: unit tests covering empty, single, and malformed appliedPromotions)
  3. Task 3: Stockroom sales API controller endpoint (Verification: MockMvc integration tests)

3. The Cross-Repository Semantic Wiki Handoff Architecture

In enterprise or multi-service ecosystems, standard in-repo SDD frameworks (e.g. AWS Kiro, GitHub Spec Kit) encounter a critical structural limitation: specifications are siloed inside a single git repository.

When building cross-service initiatives—such as customer marketing attribution spanning Roller weblogs, Stockroom warehouse events, JakeMon telemetry, and accounting general ledgers—placing a specification in stockroom/docs/specs renders it completely invisible to agents operating in roller or jakemon.

The Wikantik Technical Handoff Paradigm

Simple Agility resolves this through Semantic Wiki Handoff Specifications:

Classical In-Repo SDDSemantic Wiki-Anchored SDD (Level 5)
Stored as local Markdown inside a single repository (docs/specs/*.md)Stored centrally on Wikantik as formal specifications (RollerTelemetryHandoffSpec)
Invisible to agents working in peer repositoriesGlobally accessible to all agents via /knowledge-mcp
Prone to drift as repositories divergeBound to sovereign decision logs (SimpleAgilityDecisionLog)
Requires manual copy-pasting of schemas across PRsSingle authoritative schema cited by canonical ID
Single-agent executionSupports clean Dual-Agent Architecture (Architecture Agent → Engineering Agent)

The Dual-Agent Pattern in Practice

  1. Architecture & Content Agent (wiki-content-agent): Focuses on system-wide coordination, data modeling, SEO telemetry, and protocol handoffs. Operates under a strict architectural invariant: NEVER modify or build core product application code. Instead, it authors formal, complete specifications on Wikantik (e.g., SimpleAgilityCommerceDataFlow, SimpleAgilityAttributionRFC).
  2. Human Operator Gate: The operator reviews the published wiki specification, conducts an interactive interview (/grill-me), refines edge cases, and approves the architecture.
  3. Core Engineering Agent (Claude Code / Antigravity agy): Initialized in the operational product repository (~/source/stockroom or ~/source/roller). It retrieves the handoff specification directly from Wikantik via MCP: 
    # Agent retrieves the complete, authoritative specification cold
claude mcp call wikantik-knowledge read_pages '{"slugs": ["SimpleAgilityCommerceDataFlow"]}'

    The engineering agent implements the code strictly against the retrieved specification without guessing or cross-repo hallucination.

4. Mathematical Modeling of Defect Escape Rates

The economic justification for written specifications over conversational prompting can be proven through classical reliability mathematics.

1. Cumulative Defect Escape Probability

Software defects originate across four phases: Requirements (phase 1), Design (phase 2), Code Implementation (phase 3), and Integration Testing (phase 4). Let eta_k represent the defect detection efficiency of phase k (where 0 < eta_k < 1). The probability that a requirements-level defect escapes into production is modeled as:

P_{\text{escape}} = \prod_{k=1}^{4} \left( 1 - \eta_k \right)

Under Vibe Coding (no written spec, conversational prompting):

P_{\text{escape}} = (1 - 0.10) \times (1 - 0.15) \times (1 - 0.50) \times (1 - 0.60) = 0.90 \times 0.85 \times 0.50 \times 0.40 = 0.153 \text{ (15.3\%)}

Under Semantic Wiki SDD (EARS requirements, human-gated wiki RFC, TDD):

P_{\text{escape}} = (1 - 0.75) \times (1 - 0.80) \times (1 - 0.85) \times (1 - 0.90) = 0.25 \times 0.20 \times 0.15 \times 0.10 = 0.00075 \text{ (0.075\%)}

By inserting formal specification and design gates, the defect escape rate drops by over two orders of magnitude (204x reduction).

2. Exponential Defect Rectification Cost

The cost to fix a defect discovered at phase k follows an exponential escalation curve:

C(k) = C_0 \cdot \beta^{k-1}

Where C_0 is the baseline cost of catching a defect during initial specification (C_0 ≈ $10 in operator time), and beta is the amplification factor (beta ≈ 4.0):

Catching a data modeling error on Wikantik costs $10, whereas resolving corrupted database rows and broken inventory counts in production costs $640+.

5. Anti-Patterns in Spec-Driven Engineering

  1. Spec Theater: Instructing an agent to generate a 2,000-word specification, skipping human review, and immediately triggering implementation. The agent is simply grading its own homework; you have added latency without introducing an independent cognitive gate.
  2. Over-Specification: Specifying internal private method variable names and trivial implementation minutiae. Specify external behaviors, public interfaces, invariants, and constraints; allow the coding agent autonomy over implementation syntax.
  3. Spec Drift (The Dead Spec Anti-Pattern): Evolving code during debugging while leaving the specification unchanged. A stale specification is worse than no specification because it misleads future agents. If implementation reality forces an architectural change, update the wiki specification first.
  4. The Monolithic Mega-Spec: Authoring a 10,000-word specification spanning five separate subsystems in a single task. Decompose large architectures into modular, phased handoffs (e.g., Phase 1b vs Phase 1c on SimpleAgilityRoadmap).

See Also