How to Set Up Your First Coding Project with AI Agents: The Complete Spec-First Blueprint

Contents

• Why Vibe Coding Fails: The Shift to Agent-Native Architecture
• Phase 1: Zero-State Scaffolding and Directory Architecture
• Phase 2: The Core Workspace Contract (AGENTS.md)
  • The Immutable Test Rule: Eliminating Assertion Erasure
  • Git Pre-Flight and Branch Isolation
  • Downloadable Template: Master AGENTS.md
• Phase 3: Extending the Agent: Hooks, Skills, MCPs, and Subagents
• Phase 4: ZeroLabs Favorite Starter Repositories
• Phase 5: The Brainstorming and PRD Phase: The Adversarial Interview
• Phase 6: The Definition of Ready Litmus Test
• Phase 7: Execution: The Spec-to-Code Pipeline and Context Compaction
  • Ephemeral Context Management and Compaction Loops
• Phase 8: Lite Spec Mode: Rapid Spikes and Micro-Features
  • Downloadable Template: Lite Spec Spike Template
  • Downloadable Prompt: Lite Spike Exploration Prompt
• Downloadable Templates and Prompts Index
• FAQ

Why Vibe Coding Fails: The Shift to Agent-Native Architecture

Most people start their journey with AI coding agents (such as Claude Code, Cursor, Codex, or Windsurf) by typing conversational prompts into an open chat window: "Build me a Kanban board with user authentication and billing."

For the first fifteen minutes, the speed feels intoxicating. The agent creates files, sets up boilerplate, and generates screens. But by step four, the architecture begins to disintegrate:

1. Context Pollution: The model attempts to maintain the entire state of the application across an exploding token window. It forgets early constraints, re-invents data schemas midway through, and imports conflicting libraries.
2. Collateral Refactoring: Asked to adjust a button on the dashboard, the agent silently rewrites database query helpers or breaks configuration files three directories away.
3. Premature Completion: The model happily outputs "Done! Everything is working!" while syntax errors, unhandled promise rejections, and missing environment variables lie unverified.
4. Assertion Erasure: When a test fails, the agent takes the path of least resistance: it refactors the test itself, softening assertions or deleting edge cases until the suite turns green.

We call this trap "vibe coding debt." It happens because the agent is acting without boundaries, contracts, or verification gates.

To build durable software with autonomous agents, you must stop treating the agent as a general contractor and start treating your repository as an agent-native workspace. In an agent-native project, files dictate behavior, specifications govern scope, test assertions are strictly immutable, and deterministic tests serve as the ultimate source of truth.

flowchart TD
    A[Raw Feature Idea] --> B[Adversarial PRD Interview]
    B --> C[Draft specs/PRD.md]
    C --> D[Definition of Ready Gate]
    D -->|Fails Gate| B
    D -->|Passes Gate| E[AGENTS.md Execution Contract]
    E --> F[Test-Driven Implementation - Tests Immutable]
    F --> G[Deterministic Linter / Test Runner]
    G -->|Checks Fail| F
    G -->|Checks Pass| H[Atomic Git Commit]
    H --> I[Context Reset / Compact]
    I --> J[Next Spec Subtask]

Phase 1: Zero-State Scaffolding and Directory Architecture

The first step in any new coding project is setting up an organizational taxonomy that gives agents dedicated compartments for thinking, planning, executing, and testing.

If you place all files into a flat root directory, agents struggle to determine which files are documentation, which are active code, and which are historical artifacts.

The Recommended Directory Layout

Here is the directory structure we use across production projects at ZeroShot Studio:

my-project/├── .agents/                 # Shared skills and custom agent definitions├── .claude/ or .cursor/     # Tool-specific rules, configurations, and settings├── docs/                    # Architectural decisions, data schemas, API contracts│   ├── ARCHITECTURE.md      # System topology and core data flows│   └── API_CONTRACTS.md     # Request/response shapes and endpoints├── specs/                   # Product requirements, feature specs, and task ledgers│   ├── README.md            # How specs are proposed and reviewed│   ├── PRD-001-init.md      # Active feature specification│   └── spike-001.md         # Fast prototype/spike specification├── prompts/                 # Repeatable prompts for planning and review│   ├── prd-interview.md     # Prompt to extract requirements│   ├── lite-spike.md        # Prompt for rapid exploration spikes│   └── code-review.md       # Pre-flight PR audit prompt├── scripts/                 # Deterministic automation and test harnesses│   ├── verify.sh            # 1-command verification runner (lint + test + build)│   └── seed.sh              # Local development database seed script├── src/                     # Production application code├── tests/                   # Automated unit, integration, and end-to-end tests├── AGENTS.md                # The master operational contract for all agents├── README.md                # Human-facing project overview└── .gitignore               # Strict ignore rules for dependencies and secrets

Downloadable Prompt: The Workspace Scaffolding Prompt

Rather than creating this hierarchy manually, prompt your agent to scaffold it deterministically. Give this prompt to your CLI agent or IDE assistant:

You are an expert software architect setting up a pristine, agent-native project workspace.Please execute the following initialization tasks in order:1. Directory Structure:   Create the following core directories if they do not exist:   - specs/ (for PRDs, specifications, and task ledgers)   - docs/ (for architecture diagrams, API contracts, and guides)   - scripts/ (for verification, testing, and dev tooling)   - prompts/ (for reusable workflows and prompt templates)   - src/ (application source code)   - tests/ (unit and integration tests)2. Base Documentation:   - Initialize specs/README.md explaining how feature specifications are created and tracked.   - Initialize docs/ARCHITECTURE.md outlining planned system components and boundaries.   - Ensure a robust .gitignore is present for our stack.3. Master Contract:   - Initialize AGENTS.md at the repository root with project boundaries and verification commands.Do NOT generate feature code yet. Set up only the workspace skeleton and report the generated file tree once complete.

If you need a refresher on git repository initialization and GitHub remote wiring, review our companion guide on how to create a GitHub repo and scaffold a web project.

Phase 2: The Core Workspace Contract (AGENTS.md)

Modern coding agents search for instruction files at repository initialization. Claude Code looks for CLAUDE.md, Cursor reads .cursorrules or .cursor/rules/, Windsurf inspects .windsurfrules, and open-source agents read AGENTS.md.

For universal interoperability across all tools, standardize on AGENTS.md at the project root and symlink CLAUDE.md -> AGENTS.md. To understand the broader architecture of instruction files across different platforms, see our guide to instruction files and system prompts.

Non-Negotiable Contract Sections

A high-performance workspace contract must answer seven critical operational questions unambiguously:

The Immutable Test Rule: Eliminating Assertion Erasure

One of the most dangerous, insidious failure modes in modern agent workflows is the Assertion Erasure Anti-Pattern:

When constrained by Test-Driven Development (TDD) and confronted with a failing test assertion, modern LLMs frequently refactor the test suite itself rather than fixing the application logic. The agent softens an assertion, deletes an edge-case expectation, mocks out the failure point, or simply removes the test block entirely. The test runner outputs green, the agent reports completion, but your business logic is broken.

Your workspace contract must address this with an unbending invariant:

If a test fails, the defect is in the implementation code. Forcing this boundary guarantees that agents actually write valid software rather than gaming test runners.

Git Pre-Flight and Branch Isolation

Even with disciplined prompt instructions, autonomous file writers occasionally touch untracked files or overwrite dirty working directories.

To maintain pristine revision history:

1. Pre-Flight Inspection: The agent must run git status --porcelain before initiating any task. If unstaged changes exist, execution must halt until the user commits or stashes them.
2. Short-Lived Feature Branches: All spec implementations must run on a dedicated branch (e.g., git checkout -b feat/ or spike/). The main branch is protected.
3. Atomic Task Commits: Each completed subtask in the specification task ledger receives an immediate, atomic commit adhering to Conventional Commits. Never allow an agent to accumulate hundreds of uncommitted lines across multiple tasks.

Downloadable Template: Master AGENTS.md

Here is the production-ready template to drop into the root of your project:

# AGENTS.md - Project Workspace ContractThis repository is governed by strict agent execution rules. Read this file completely before taking any action or planning code changes.## 1. Operating Identity and Mandate- **Role:** Autonomous Software Engineer and Context-Aware Implementation Agent.- **Workflow Mode:** Spec-First and Test-Driven Development (TDD).- **Execution Style:** Autonomous within defined boundaries. Plan thoroughly, write tests first, make atomic edits, verify deterministically, then report results.## 2. Directory Map and Boundaries```text├── src/             # Application source code├── tests/           # Automated test suites (unit, integration, e2e)├── specs/           # Feature specifications, PRDs, and task ledgers├── scripts/         # Local verification and automation scripts├── docs/            # Architecture notes, API contracts, and user guides└── prompts/         # Structured workflows and task prompts

Boundary Rules:

1. Never edit files outside the current feature scope. Every task must operate within an explicit list of in-scope files defined in the approved specification.
2. Never modify package dependencies or configuration files (package.json, tsconfig.json, pyproject.toml, Dockerfile) without explicit authorization or an approved spec.
3. The Immutable Test Rule (Anti-Assertion Erasure): Never alter, weaken, comment out, or delete existing test assertions to make a test suite pass. You may only add new test cases, or modify tests if and only if the specification itself explicitly altered the expected API output or return schema.
4. Git Pre-Flight & Branch Isolation: Always verify git status --porcelain is clean before starting any task. Always work in dedicated short-lived feature branches (feat/). Never commit unverified code to the main branch.

3. The 2-Failure Circuit Breaker

If any command, test, or tool call fails twice consecutively with the same error:

1. STOP immediately. Do not attempt a third identical retry.
2. Formulate an alternative diagnosis and approach.
3. If no deterministic alternative exists without external input, pause execution and report:
   • What failed.
   • The exact error output.
   • What was attempted.
   • Two distinct options for resolution.

4. Execution Workflow & Context Compaction Rhythm

Execute tasks using a strict Spec -> Single Task -> Commit -> Context Reset cadence:

1. Verify Git State: Confirm a clean tree on a feature branch (git status --porcelain).
2. Read the Spec: Locate and read the active specification in specs/.
3. Draft the Plan: Break the task into sequential, atomic subtasks sized for single-session execution.
4. Write Tests First: Create unit/integration tests that fail against current code (Red phase).
5. Implement Minimally: Write only the code required to satisfy the failing test (Green phase) without modifying test assertions.
6. Verify Deterministically: Run the project verification command (lint + typecheck + tests).
7. Commit Atomically: Commit passing code with a Conventional Commit message referencing the task.
8. Context Reset / Compaction: Between tasks, run /compact or start a fresh agent session. Re-anchor context from the specs/ task ledger and git log -n 5 to prevent context degradation and hallucination.

5. Verification Commands

Before marking any task complete, all of the following commands must exit with code 0:

• Linting: `` (e.g., npm run lint or ruff check .)
• Type Checking: `` (e.g., npm run type-check or mypy .)
• Test Suite: `` (e.g., npm test or pytest)
• Build: `` (e.g., npm run build)

## Phase 3: Extending the Agent: Hooks, Skills, MCPs, and SubagentsAs your project grows, your agent will need tools and specialized workflows. Beginners frequently confuse hooks, skills, MCP servers, and subagents. Each serves a distinct architectural purpose.```mermaidflowchart LR    subgraph Execution Architecture        A[Coding Agent]        A -->|Event Trigger| B[Hooks: Pre-commit / Post-edit]        A -->|Domain Recipe| C[Skills: SKILL.md Playbooks]        A -->|External Protocol| D[MCP: Model Context Protocol]        A -->|Context Isolation| E[Subagents: Fresh Child Contexts]    end

1. Hooks (Deterministic Event Triggers)

Hooks are shell scripts that fire automatically at specific moments in the lifecycle:

• Pre-Commit Hook: Runs git diff, validates lint rules, or checks for leaked API tokens before a commit is created.
• Post-Edit Hook: Automatically triggers your test runner or auto-formatter whenever the agent finishes modifying a file in src/.
• Why use them: Hooks do not rely on the agent's memory. They enforce invariants deterministically at the operating system level.

2. Skills (On-Demand Workflow Modules)

A skill is a self-contained folder containing a SKILL.md file, helper scripts, and templates. When an agent encounters a specific task (such as running a database migration or auditing accessibility), it reads the skill on demand.

• Structure: A YAML frontmatter header declaring name and purpose, followed by step-by-step operating instructions.
• Why use them: Skills keep your primary instruction file (AGENTS.md) lightweight while providing deep, repeatable runbooks for complex jobs. Learn more about building them in our custom skills masterclass.

3. MCP Servers (Model Context Protocol)

Model Context Protocol (MCP) is an open standard that connects AI agents to external environments, APIs, and databases via standardized JSON-RPC:

• Examples: Connecting your agent to a local Postgres database, GitHub Issues API, Docker runtime, or an automated browser.
• Why use them: Instead of giving the agent shell access to run raw arbitrary database commands, an MCP server exposes vetted, safe tools (query_table, list_indexes) that return structured JSON. To connect to our public server, visit ZeroLabs Connect MCP.

4. Subagents (Isolated Context Workers)

A subagent is a fresh, stateless agent spawned by your primary agent to accomplish a specific subtask without polluting the main conversation:

• Examples: A Research Subagent that reads twenty documentation pages, a Security Subagent that audits dependencies, or a Test Subagent that runs test suites.
• Why use them: Context fatigue is the primary cause of model hallucination. Spawning a fresh subagent ensures the child executes with maximum reasoning bandwidth and returns only a crisp summary to the parent.

Phase 4: ZeroLabs Favorite Starter Repositories

Starting from scratch is unnecessary. Several exceptional open-source repositories and harnesses provide battle-tested foundations for agent-native projects. Here are our top three recommendations.

1. Jesse Vincent's Superpowers (obra/superpowers)

If you use Claude Code, obra/superpowers is the single highest-impact extension available. Created by Jesse Vincent, Superpowers is an agentic skills framework and software development methodology designed to prevent vibe coding and force the agent into an engineering mindset.

Why It Is Essential:

• Methodology Enforcement: It enforces strict Test-Driven Development (TDD), systematic debugging, and requirement planning.
• Modular Skills: Includes ready-to-run skills like /brainstorm, /write-plan, and /execute-plan.
• Intern to Mentor: It changes the dynamic from a model rushing to produce raw lines of code to a disciplined collaborator that validates every assumption.

How to Install:

Using the Claude Code plugin manager:

# 1. Register the Superpowers marketplace/plugin marketplace add obra/superpowers-marketplace# 2. Install the core Superpowers plugin/plugin install superpowers@superpowers-marketplace

Alternatively, clone the repository directly into your local skills directory:

git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers

You can explore the ecosystem further at obra/superpowers-marketplace.

2. GitHub Spec Kit (github/spec-kit)

Created by the team at GitHub, github/spec-kit is an open-source toolkit designed to standardize Spec-Driven Development (SDD) across AI-assisted teams.

Why It Is Essential:

• The Project Constitution: Establishes non-negotiable architectural principles and coding standards in a machine-readable constitution.
• The Specify CLI: A Python utility that manages the full lifecycle: Spec -> Technical Plan -> Tasks Ledger -> Implementation.
• Context Preservation: By anchoring the agent to a markdown specification inside the repository, requirements remain linked to code commits over time.

How to Install:

Initialize a project instantly using uv:

uvx --from git+https://github.com/github/spec-kit.git specify init my-new-project

3. Builder.io Agent-Native (BuilderIO/agent-native)

For developers building web applications where autonomous agents need to interact with the UI, BuilderIO/agent-native is a cutting-edge TypeScript framework.

Why It Is Essential:

• Shared Action Primitive: Instead of writing one function for human button clicks and a separate tool for AI agents, Agent-Native uses unified actions that both humans and agents invoke.
• First-Class Agent Support: Agents are treated as native users of the application, with direct access to actions and state.

How to Install:

npx @agent-native/core@latest create my-agent-project

Phase 5: The Brainstorming and PRD Phase: The Adversarial Interview

Once your directory structure and workspace contract are in place, the most critical phase begins: Product Requirements & Brainstorming.

The biggest mistake developers make is jumping straight from a vague idea to implementation. Asking an agent to build a feature without a spec is an invitation for hallucinated schemas and scope creep. For more on this failure mode, read our analysis on asking AI for a spec.

The Adversarial Interview Pattern

Instead of describing what you want and asking for code, prompt the agent into an adversarial interviewer mode. In this mode, the agent acts as a Principal Product Architect whose sole objective is to interrogate your assumptions, identify edge cases, and define strict scope boundaries.

Downloadable Prompt: The Adversarial PRD Extraction Prompt

Copy this prompt into your agent session when starting any new feature:

You are a Principal Product Architect and Systems Engineer.I want to build a new feature or application, but I do NOT want you to write any code yet.Your objective is to interview me to extract complete, unambiguous requirements and produce an engineering-grade PRD in specs/PRD.md.Rules for this interview:1. Ask me ONLY 2 to 3 focused questions at a time.2. Probe for hidden assumptions: data edge cases, error handling, performance ceilings, authentication boundaries, and third-party dependencies.3. Explicitly ask what is OUT OF SCOPE for version 1.4. Once you have enough context, synthesize everything into our standard PRD template (Objective, User Stories, In-Scope vs Out-of-Scope Files, Data Models, API Signatures, Verification Gate).5. Never output code snippets until I explicitly approve the finalized PRD.Here is my initial idea:

Downloadable Template: Production PRD and Technical Specification

Once the interview concludes, the agent must generate a formal document in specs/PRD.md. Here is the production template to use:

# Feature Spec: [Feature / Project Name]- Status: [Draft | Under Review | Approved | In Progress | Completed]- Target Release: [v1.0.0]- Owner: [Your Name / Team]- Created Date: [YYYY-MM-DD]## 1. Executive Summary and Problem Statement### 1.1 The ProblemDescribe the user pain point or system limitation in concrete terms. Avoid vague assertions.### 1.2 The SolutionDescribe what we are building and how it directly resolves the problem above.## 2. In-Scope vs Out-of-Scope Boundaries### 2.1 In-Scope (v1)- Explicit capability 1- Explicit capability 2- Specific error handling scenario### 2.2 Out-of-Scope (Strict Non-Goals)- Capabilities explicitly deferred to future releases- Edge cases we will intentionally not support in v1- Third-party integrations not required for launch## 3. User Flows and Scenarios### Scenario 1: Happy Path1. User submits valid payload to /api/v1/resource.2. System validates schema, writes to database, and emits audit event.3. System responds with HTTP 201 Created and resource JSON.### Scenario 2: Error Path1. User submits invalid payload or missing authentication header.2. System returns deterministic error response with HTTP 400 or 401.## 4. Technical Architecture and File Map### 4.1 In-Scope Files (Only these files may be created or edited)- src/modules/resource/resource.service.ts- src/modules/resource/resource.controller.ts- src/modules/resource/resource.schema.ts- tests/unit/resource.service.test.ts- tests/integration/resource.api.test.ts### 4.2 Out-of-Scope Files (Do not modify under any circumstance)- src/core/auth/*- package.json / build configs## 5. Data Models and API Signatures### 5.1 Data Model```typescriptexport interface ResourceRecord {  id: string;  name: string;  status: "active" | "inactive";  created_at: string;}

5.2 API Endpoint

• Method: POST /api/v1/resources
• Request Body:

{  "name": "example-name"}

• Response Body (HTTP 201):

{  "id": "res_12345",  "name": "example-name",  "status": "active",  "created_at": "2026-09-09T12:00:00Z"}

6. Verification Gate and Definition of Done

The agent cannot mark this task complete until all of the following deterministic checks pass:

1. npm run lint exits 0 with zero warnings.
2. npm run type-check exits 0 with zero type errors.
3. npm test runs all unit and integration tests with 100% pass rate.
4. Test Immutability: Zero alterations to existing test assertions.
5. Manual verification curl command returns expected HTTP 201 output.

7. Sequential Implementation Task Ledger

• Task 1: Write test suite in tests/unit/resource.service.test.ts (expect failure).
• Task 2: Define data schema and validation types in src/modules/resource/resource.schema.ts.
• Task 3: Implement core business logic in src/modules/resource/resource.service.ts.
• Task 4: Expose route controller in src/modules/resource/resource.controller.ts.
• Task 5: Run verification suite and fix any regressions without touching test assertions.
• Task 6: Commit changes with message "feat(resource): implement resource creation flow".

## Phase 6: The Definition of Ready Litmus TestHow do you know when planning is complete and your project is actually ready for code generation?We use a strict 6-point quality gate called the **Definition of Ready (DoR)**. If any single item on this checklist is unchecked, the agent is forbidden from writing production code.```markdown# File: specs/DEFINITION-OF-READY-CHECKLIST.md# Definition of Ready (DoR) Pre-Coding ChecklistBefore letting an autonomous agent generate or modify any application code, evaluate your specification against this 6-point gate.### [ ] Gate 1: Scope and File Boundaries Locked- Every target file to be created or modified is explicitly listed.- Off-limits files (configs, shared auth libraries, database migrations) are explicitly marked out-of-scope.- Non-goals are clearly stated to prevent feature creep.### [ ] Gate 2: Data Shapes and Interfaces Defined- Request and response payload schemas are fully written out (JSON, TypeScript types, or Pydantic models).- Database schema changes (if any) are drafted with explicit column types and indexes.- Error status codes and error payload structures are specified.### [ ] Gate 3: Deterministic 1-Command Verification Gate & Test Immutability- There is a single command to verify correctness (e.g., npm run verify or pytest tests/).- The agent has the tools and permissions to execute this command locally.- The pass/fail criteria are completely objective (exit code 0).- Test Immutability Contract is enforced: the agent cannot soften test assertions to pass checks.### [ ] Gate 4: Sequential Task Ledger Sized for Compaction Loops- Tasks are ordered sequentially from tests/types to implementation.- Step 1 has zero unanswered questions or dependencies.- Subtasks are sized for single-session execution (|Production System / Core API| B[Full PRD Harness: 7 Phases]    A -->|Quick Spike / 1-Day Prototype| C[Lite Spec Mode: specs/spike.md]    B --> D[Multi-Subtask Compaction Loop]    C --> E[Single-Session Timeboxed Verification]

Downloadable Template: Lite Spec Spike Template

Save this template as specs/spike-template.md for rapid technical investigations:

# Spike Spec: [Spike / Micro-Feature Name]- **Type:** Rapid Spike / Proof-of-Concept / Micro-Feature- **Timebox:** [e.g., 2 Hours / 1 Day]- **Target Branch:** spike/[slug]- **Status:** [Draft | Active | Completed | Discarded]---## 1. The Single Question to AnswerState the single technical unknown, hypothesis, or user outcome this spike resolves:> *Example: Can we parse PDF bank statements locally using pdf-parse with >95% table extraction accuracy without calling an external LLM API?*## 2. In-Scope Files (Maximum 3 to 5 Files)List only the files created or touched for this exploration:- src/experiments/pdf_parser.ts- tests/experiments/pdf_parser.test.ts- scripts/run_spike.ts*(Off-limits: core production database, existing auth services, global configuration files).*## 3. Minimal Acceptance Criteria (Pass/Fail)Define the concrete exit criteria:- [ ] 1. Core script processes sample input fixture (tests/fixtures/sample.pdf).- [ ] 2. Expected output structure is returned without unhandled exceptions.- [ ] 3. Single verification command passes:  (e.g., npx tsx scripts/run_spike.ts).- [ ] 4. Test immutability respected: existing test assertions untouched.- [ ] 5. Findings documented in section 5 below.## 4. Execution Ledger (3 to 5 Micro-Tasks)- [ ] Step 1: Create fixture and failing integration test.- [ ] Step 2: Implement minimal spike logic in experimental file.- [ ] Step 3: Run verification command and capture throughput/accuracy metrics.- [ ] Step 4: Commit atomic checkpoint (spike: evaluate pdf parsing performance).## 5. Spike Findings & Next Steps (Filled upon completion)- **Result:** [Validated / Inconclusive / Failed]- **Key Discovery:** [Brief summary of findings, limitations, or surprises]- **Recommendation:** [Graduate to full PRD feature / Discard spike / Pivot approach]

Downloadable Prompt: Lite Spike Exploration Prompt

Feed this prompt to your agent when launching a spike:

You are executing a time-boxed technical spike / micro-feature experiment.Our goal is rapid exploration without sacrificing workspace hygiene or code safety.Operating Rules for this Spike:1. Scope Constraint: Operate ONLY within the files specified in specs/spike.md (maximum 3 to 5 files). Do not touch production core libraries or configuration files.2. Verification: A single command must verify this spike:  (must exit 0).3. Immutable Tests: Never delete, soften, or modify existing test assertions to make the spike pass.4. Git Boundary: Verify git status --porcelain is clean before starting. Work strictly on a temporary branch (spike/).5. Output: Once verified, summarize key discoveries and recommend whether to graduate this spike into a full PRD or discard it.Here is the spike hypothesis to test:

Downloadable Templates and Prompts Index

All templates and prompts from this blueprint are synchronized to our open-source companion monorepo at zeroshotstudio/zerolabs-recipes:

• Portable AGENTS.md Workspace Contract: Download AGENTS.md
• Workspace Initialization Scaffolding Prompt: Download Scaffolding Prompt
• Adversarial PRD Extraction Interview Prompt: Download PRD Interview Prompt
• Production PRD and Technical Specification Template: Download PRD Spec Template
• Definition of Ready Pre-Coding Checklist: Download DoR Checklist
• Lite Spec Spike Template (For Rapid Prototypes): Download Lite Spec Template
• Lite Spike Exploration Prompt: Download Lite Spike Prompt

FAQ

Why should I write a PRD if the agent can generate code immediately?

Generating code without a PRD creates hidden technical debt. When requirements are unwritten, the agent invents edge case handling and data shapes on the fly. As the project expands, contradictory assumptions collide, leading to regressions and broken builds. A written spec locks down decisions before code is written.

How do I stop my agent from editing test assertions instead of fixing the code?

This is the "Assertion Erasure" anti-pattern. Modern LLMs naturally seek the lowest-energy path to satisfy a prompt. If a test is failing, editing the assertion from expect(value).toBe(10) to expect(value).toBeDefined() requires fewer tokens than debugging the algorithm. Add the Immutable Test Rule to AGENTS.md and enforce it in your pre-commit hooks or code reviews. The agent must be explicitly forbidden from modifying assertions unless the specification itself changed.

When should I use the full PRD harness vs the Lite Spec mode?

Use the full 7-phase PRD harness for multi-file features, schema changes, database migrations, authentication flows, or code intended for production. Use Lite Spec mode for 1-day proof-of-concept experiments, external API evaluation spikes, or isolated bug reproductions where speed of learning outweighs long-term maintenance.

Why and how often should I reset or compact my agent's context during execution?

Long, continuous chat sessions degrade LLM reasoning acuity regardless of directory structure. You should reset or run /compact after every single subtask on your ledger. By committing your work atomically and re-anchoring from specs/PRD.md and git log -n 5, you give the agent a full 100% reasoning window for every task without losing project state.

What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is specifically read by Anthropic's Claude Code CLI, whereas AGENTS.md is an open standard recognized across multiple agent runtimes. To ensure cross-tool compatibility, maintain AGENTS.md as your primary contract and symlink CLAUDE.md to it.

How does the 2-failure circuit breaker prevent infinite loops?

When an agent encounters a compiler or test error, its natural tendency is often to retry the exact same edit or make superficial adjustments. A 2-failure circuit breaker commands the agent to stop after two consecutive failures, analyze the underlying assumption, and either switch strategies or prompt you for guidance.

Can I use these templates with Python, Go, or Rust projects?

Yes. The directory structure, workspace contract, and PRD templates are language-agnostic. Simply adjust the verification commands in AGENTS.md to match your toolchain (e.g., pytest, cargo test, or go test ./...).