What is a spec?
A spec is a markdown file that describes what you want built. It is the only input UseZombie needs to produce a validated pull request. No chat prompts, no ticket descriptions, no Slack threads. One file, checked into git, describing the work.
Example spec
# Add rate limiting to the /api/jobs endpoint
## Goal
Prevent abuse by adding token-bucket rate limiting to the jobs endpoint.
Limit unauthenticated requests to 20/min and authenticated requests to 100/min.
## Files to modify
- src/middleware/rateLimit.ts (new file)
- src/routes/api/jobs.ts (add middleware)
- src/config/defaults.ts (add rate limit constants)
- tests/middleware/rateLimit.test.ts (new file)
## Acceptance criteria
- Unauthenticated requests exceeding 20/min receive HTTP 429
- Authenticated requests exceeding 100/min receive HTTP 429
- Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are present on every response
- Existing /api/jobs tests continue to pass
- New unit tests cover both authenticated and unauthenticated limits
Tips for effective specs
Be specific about file paths. Instead of “add a middleware,” write src/middleware/rateLimit.ts. Explicit paths give the agent a clear target and improve context injection (see below).
Describe expected behavior, not implementation steps. Write “unauthenticated requests exceeding 20/min receive HTTP 429” rather than “use an if-statement to check the counter.” Agents are better at choosing implementation details when you define the outcome.
Include acceptance criteria. These become the agent’s verification targets. Each criterion is something the agent will attempt to prove before marking the run complete.
Reference existing patterns. If your codebase already has a middleware pattern, mention it: “Follow the same pattern as src/middleware/auth.ts.” This anchors the agent to your conventions.
Context injection
UseZombie extracts file references from your spec markdown and matches them against the repository file tree. Every matching file is provided as context to the agent alongside the spec content.
This is critical for accurate implementations. When the spec says src/routes/api/jobs.ts, the agent receives that file’s full contents and can see the existing code structure, imports, and conventions before making changes.
The more specific your file references, the better the agent’s context window. Vague references like “the routes folder” provide no context. Explicit paths like src/routes/api/jobs.ts provide the exact file the agent needs.
Reference files that the agent should read but not modify, too. Mentioning src/middleware/auth.ts as a pattern reference injects it into context even if the spec does not ask the agent to change it.
Generating a spec template
zombiectl spec init is a future feature. Today, create specs as plain markdown files in your repository.
Spec as the single source of truth
Specs are versioned in git. There is no prompt archaeology, no chat history to reconstruct, no “what did we tell the AI last time?” Every run references a specific spec file at a specific commit. If the spec changes, the next run uses the new version.
This means:
- Reviewable. Specs go through pull request review like any other code.
- Reproducible. Re-running the same spec on the same base commit produces the same run.
- Auditable. Git history shows what was requested, when, and by whom.
- Handoff-friendly. A new team member reads the spec to understand what was built and why.
No chat transcripts. No prompt files buried in .ai/ directories. The spec is the contract between you and the agent.
