Spec, audit, and maintain is a workflow for undead apps vibe coding maintenance that prevents AI-generated projects from decaying into unmaintainable ghost repositories. It treats markdown specifications and contract schemas as the durable source of truth, forcing every agent generation loop through automated type checks, contract tests, and human model-off review before code enters production.
The workflow at a glance
flowchart LR
A[Author specification] --> B[Generate contract tests]
B --> C[Constrained prompt implementation]
C --> D[Run deterministic exit gate]
D --> E{Gate passes?}
E -- no --> F[Feed trace and spec back to agent]
F --> C
E -- yes --> G[Human model-off inspection]
G --> H[Commit to branch]
When to use it
- Shared team codebases where multiple developers must understand and maintain architectural context.
- Core business APIs, billing guards, and domain logic where silent regressions cause data corruption or security exploits.
- Long-lived projects intended to run in production for more than three months.
Skip it for disposable 48-hour hackathon prototypes or one-off exploratory visual wireframes where code will be discarded.
Step 1: Formalize intent in a living specification
- Do: Author or update a specification document in
specs/before prompting the agent for implementation code. Define explicit I/O boundaries with static schemas using Zod or Pydantic, document state invariants, and list explicit acceptance criteria. - Output: A specification file (such as
specs/features/auth-billing.md) that serves as the single source of truth for the change.
Step 2: Generate failing contract tests
- Do: Instruct the agent to read the specification and generate invariant and negative tests in
tests/contracts/. Forbid the agent from writing implementation code insrc/during this step. Execute the test suite to confirm every new test fails. - Output: A failing test suite establishing deterministic verification boundaries before implementation begins.
Step 3: Implement under bounded constraints
- Do: Prompt the agent to write the implementation in
src/strictly to satisfy the specification and pass the failing tests. Explicitly instruct the model not to mutate existing schema definitions, delete validation guards, or install third-party dependencies. To protect foundational project layers from widespread edits, isolate work using Git Worktrees: A Workflow for Running Parallel Agents. - Output: Minimal source code changes strictly scoped to the feature requirements.
Step 4: Run deterministic exit gates
- Do: Execute an automated verification script before accepting any generation run. The gate must enforce type safety (
tsc --noEmitormypy), linting with zero warnings, contract test execution, and dependency audits to catch unapproved packages. If errors occur, feed the terminal traceback along with the original specification back into the prompt loop. - Output: A clean pass from
./scripts/prompt-exit-gate.shverifying that the code meets all architectural constraints.
Step 5: Perform the model-off sanity check
- Do: Inspect the Git diff without using an AI assistant. Confirm you can trace data flow across interfaces and articulate why any change was made. Reject the PR if a developer cannot explain the implementation without querying a model, applying the oversight standards in AI Agent Oversight: Why Passive Approval Fails Systems.
- Output: A verified commit that preserves team comprehension and prevents architectural amnesia.
Variations
- Dual-mode discovery: Use fast, freeform vibe prompts for early UI exploration, then lock the resulting design behind formal schemas and exit gates before merging to main.
- Rule anchors: Place persistent constraints in
.cursor/rules/spec-driven.mdcorCLAUDE.mdto prevent agents from editingsrc/without checkingspecs/first. - Upstream planning: Generate complete task plans and invariant specifications before opening an editor, following the structure in Spec, Plan, Build, Review: A Workflow for Agent Coding.
Frequently asked questions
What is an undead app or ghost repo?
An undead app runs in production but has been cognitively abandoned. It occurs when software is assembled across ephemeral LLM chat sessions without shared architecture. If developers cannot trace data flow, understand side effects, or patch regressions once model access is removed, the repository is a ghost repo.
Why not let the agent write tests and code together?
Allowing an agent to generate tests and implementation code in the same prompt produces tautological tests. The model writes mocks against its own hallucinated logic, resulting in high test coverage that fails completely in production. Writing contract tests against an explicit specification first guarantees independent verification.
How do you fix bugs without causing hot-patching?
Never paste raw stack traces into an LLM with only a prompt to fix the error. Models often resolve raw errors by stripping validation guards or deleting auth checks. Always pass the original specification alongside the error trace and instruct the model to preserve all defined invariants.