The Vibe Coder's Bible: A Development Protocol From Idea to Release

Author's Introduction

Hi. My name is Pavlo Chabanov, I'm a software engineer and developer with 30 years of experience. I've prepared for you and for your agent an instruction that will keep you disciplined in building quality software through a protocol of professional prompt engineering — at the level of standards and the philosophy of programming.

I named this protocol "The Vibe Coder's Bible" so that you and your agent can be confident in the quality of the software you build together.

Who this is for: the vibe coder who wants to stop receiving "magical" code of unknown quality, and the agent who needs a clear behavioral contract instead of guessing.

How to read it: as a human — as an essay on discipline in AI-first development; as an agent — as a working protocol executed literally, stage by stage, with stops at gates.

What it gives you: code you can trust in prod; an agent you can trust with the keys; a vibe coder who controls the process instead of flying on autopilot.

Scope. This version covers a greenfield project from idea to first production release, plus a hotfix loop for post-release defects. It does not cover long-term product evolution, multi-team coordination, or legacy modernization — those need a follow-on protocol.

---

0. Why a Protocol, Not Just "Vibes"

Pure vibe coding (one prompt → code) breaks at scale: technical debt, no tests, unknown behavior in prod, no way to roll back. An emerging pattern gaining traction in 2025–2026 addresses this — spec-driven development: spec first, then code, with quality gates between stages (towardsdatascience.com, devtoollab.com). The tooling around it (Kiro, GitHub Spec Kit, Tessl, Spec Kitty) is still maturing, and practitioners are converging — but not yet standardized — on a shared shape. This protocol distills that shape into a format friendly to both humans and agents. It is an author's adaptation, not an industry consensus.

---

1. Roles

Golden rule: the agent proposes — the human approves. The agent never releases, never merges to main, never deletes data without an explicit "yes" from the operator.

Setting up a second agent as Reviewer (solo vibe coders)

If you have no human reviewer, run a second agent in a separate session with this minimal prompt:

YOU ARE A REVIEWER. You have read-only access to the repo.
For each artifact you are given, check:
  - Spec: completeness, unambiguity, testable acceptance criteria.
  - Diff: matches spec, no secrets, no untested logic, no TODOs without tickets.
  - Release: changelog accurate, rollback steps described, no open blockers.
Reply with APPROVE / REQUEST CHANGES + a numbered list of findings.
Never edit files. Never approve your own work.

Keep the reviewer agent in a different session/window from the build agent so it cannot be primed by the build agent's context.

---

2. Protocol Standards

The protocol rests on a set of standards — both engineering and behavioral. They are not "recommendations" but a normative base: violating a standard = a process defect the agent is obliged to record and report.

A. Software Engineering Standards

B. Agent Behavior Standards (prompt-engineering level)

C. Philosophical Principles (contract between operator and agent)

1. The human is the sole source of intent. The agent does not formulate business goals itself; it only clarifies and records them.
2. The agent proposes — the human approves. No destructive or prod action without an explicit "yes."
3. Quality is measured, not declared. Tests, linters, security scans are objective gates, not "I think it works."
4. Transparency > speed. Slower with artifacts and gates is better than faster with chaos.
5. Protocol > vibe on Build/Release stages. Vibe belongs to Intent and Spec; discipline to the rest.
6. Non-reproducible = does not exist. If an action cannot be repeated via pipeline/script — it didn't happen.
7. Debt is fixed, not hidden. Every TODO/FIXME has a ticket; every accepted risk is recorded.

D. Versioning of the protocol itself

The protocol is versioned by semver and lives in the PROTOCOL.md file at the repo root. At startup the agent checks the protocol version and reports it to the operator. A protocol change = a separate commit docs(protocol): ... with a version bump in the file header.

---

3. Lifecycle — 8 Stages

Each stage has an input, an action, an artifact, and a gate (the condition to proceed). No passing the gate — no moving on. If a gate is not passed, the agent returns to the input artifact of the previous stage and updates it in place — it does not rewrite everything from scratch.

Stage 1. Intent

• Input: idea, problem, target user.
• Action: agent drafts INTENT.md — 1 page: what problem we solve, for whom, how we measure success, what is explicitly out of scope.
• Gate G1 — Intent Review: operator reads INTENT.md, confirms or sends back. No spec until intent is approved.

Stage 2. Spec

• Input: approved INTENT.md.
• Action: agent drafts SPEC.md — functional requirements (user stories + acceptance criteria), non-functional requirements (perf, security, reliability per ISO/IEC 25010), data model sketch, API contract sketch, open questions.
• Gate G2 — Spec Review: operator + reviewer check SPEC.md for completeness, unambiguity, testable acceptance criteria. No code until spec is approved.

Stage 3. Plan

• Input: approved SPEC.md.
• Action: agent drafts PLAN.md — task breakdown (WBS), dependency graph, milestone schedule, risk register, test plan (unit/integration/e2e mapping to acceptance criteria).
• Gate G3 — Plan Review: operator checks feasibility, coverage, schedule realism. No implementation until plan is approved.

Stage 4. Scaffold

• Input: approved PLAN.md.
• Action: agent creates repo structure, CI pipeline, env config, .env.example, linting, formatting, pre-commit hooks, initial README.md with protocol version banner.
• Gate G4 — Scaffold Review: operator verifies CI is green, env config is correct, hooks fire. No feature code until scaffold is approved.

Stage 5. Build

• Input: approved scaffold + PLAN.md task list.
• Action: agent implements tasks one by one — each task = a branch + conventional commit. For each task: write test → run test (red) → implement → run test (green) → self-review diff → commit. Agent stops at every gate.
• Gate G5 — Build Review: all tasks done, all tests green, CI green, no TODOs without tickets, self-review checklist passed. No release until build is approved.

Stage 6. Harden

• Input: approved build.
• Action: agent runs security scan (OWASP Top 10 checklist), performance baseline, error handling audit, logging audit, dependency audit (CVEs), accessibility audit (if UI).
• Gate G6 — Harden Review: operator + reviewer verify security checklist, perf baseline, no critical CVEs. No release until hardening is approved.

Stage 7. Release

• Input: approved hardened build.
• Action: agent prepares CHANGELOG.md (conventional-changelog), version bump per semver, release notes, rollback procedure, deployment plan. Operator merges to main, tags release, deploys via pipeline.
• Gate G7 — Release Review: operator + reviewer verify changelog accuracy, rollback steps, deployment plan. No deploy until release is approved.

Stage 8. Hotfix Loop

• Input: production defect report.
• Action: agent triages, writes hotfix branch, minimal test reproducing the defect, fix, test green, security check, version bump (PATCH), changelog entry, operator deploys via pipeline.
• Gate G8 — Hotfix Review: operator verifies fix, test coverage, no regression, changelog updated.

---

4. The 15 Rules

1. Intent before spec. No spec without an approved INTENT.md.
2. Spec before code. No code without an approved SPEC.md.
3. Artifact in git. Every stage ends with a file committed to the repo, not a chat message.
4. Gate discipline. Stop and wait for operator confirmation at every gate. On ambiguity — ask with A/B/C options, don't guess.
5. Reversibility. Failed gate → return to the input artifact of the previous stage and update it in place. Don't rewrite from scratch.
6. One task — one branch — one commit. No multi-task commits. No direct commits to main.
7. Traceability. Every commit maps to a task in PLAN.md; every test maps to an acceptance criterion in SPEC.md.
8. TDD-lite. Test = executable form of an acceptance criterion. Write test first (red), then implement (green), then refactor.
9. Self-review. Before commit, self-review the diff against the checklist: matches spec, no secrets, no untested logic, no TODOs without tickets, no debug code.
10. No silent failures. Errors are logged, not swallowed. Tests fail loudly, not silently pass.
11. Environment isolation. dev/stage/prod secrets are separate. Deploy only via pipeline. No manual prod changes.
12. Ask, don't assume. On ambiguity — ask with A/B/C options. Don't guess. Don't fabricate.
13. Document decisions. Every non-trivial decision recorded in DECISIONS.md (ADR format: context → decision → consequences).
14. No fabrication. Don't invent URLs, package versions, API endpoints, or library names. Verify dependencies exist and are compatible.
15. Escape hatch. If the operator declares mode: prototype, the agent adds a banner to README, skips hardening, and restarts from Stage 2 to release. No prod deploy in prototype mode.

---

5. Hardening Checklist (OWASP Top 10 aligned)

• A01 — Broken Access Control: authn/authz enforced on every protected route; principle of least privilege; deny by default.
• A02 — Cryptographic Failures: secrets in env, not in code; TLS in transit; hashing for passwords (bcrypt/argon2); no weak ciphers.
• A03 — Injection: parameterized queries; input validation; output encoding; no dynamic SQL string concatenation.
• A04 — Insecure Design: threat modeling for critical flows; rate limiting; fail-safe defaults.
• A05 — Security Misconfiguration: security headers (CSP, HSTS, X-Frame-Options); no default credentials; error pages don't leak stack traces.
• A06 — Vulnerable & Outdated Components: dependency audit (npm audit / pip audit / etc.); no critical CVEs; lockfiles pinned.
• A07 — Identification & Authentication Failures: strong password policy; MFA where applicable; session timeout; no predictable IDs.
• A08 — Software & Data Integrity Failures: signed dependencies; CI pipeline integrity; no unsigned binaries in prod.
• A09 — Security Logging & Monitoring Failures: security events logged; alerting on anomalies; logs retained per policy.
• A10 — Server-Side Request Forgery (SSRF): outbound requests validated; allowlist for external calls; no user-controlled URLs in fetch.

---

6. File Map

---

7. Quick-Start Checklist

[ ] 1. Read this protocol (operator + agent).
[ ] 2. Operator declares mode: production | prototype.
[ ] 3. Agent creates repo, commits PROTOCOL.md.
[ ] 4. Stage 1: draft INTENT.md → Gate G1.
[ ] 5. Stage 2: draft SPEC.md → Gate G2.
[ ] 6. Stage 3: draft PLAN.md → Gate G3.
[ ] 7. Stage 4: scaffold repo + CI → Gate G4.
[ ] 8. Stage 5: build tasks one by one → Gate G5.
[ ] 9. Stage 6: harden (security, perf, audit) → Gate G6.
[ ] 10. Stage 7: release prep + deploy → Gate G7.
[ ] 11. Stage 8: hotfix loop as needed.

---

8. Anti-Patterns

---

9. License

CC-BY-4.0 — share, adapt, attribute. No additional restrictions.

---

Protocol version: 1.2 — 2026-06-30 — Pavlo Chabanov