Vibe Coding Standard

Build software with AI agents as the primary developers.

This repository provides a gold-standard AI-first repository structure designed for projects where:

• AI agents implement most code
• humans guide and review the work
• the codebase grows incrementally and predictably

The structure, workflow, and documentation are designed to make repositories:

• easy for AI agents to understand
• safe for agents to modify
• predictable for humans to review

What is Vibe Coding?

Vibe coding is a development style where:

humans define intent
AI agents implement the system
humans guide architecture and decisions

Instead of manually writing every file, developers focus on:

• defining the problem
• describing the behavior
• guiding the architecture

AI agents then implement, test, and maintain the code.

Core Idea

The repository is optimized for collaboration between:

• AI coding agents
• AI orchestration systems
• human developers

The design prioritizes:

• clarity
• traceability
• predictable structure
• incremental architecture

Development follows two core ideas:

specification-driven development
+
progressive repository expansion

The Minimal Starting Point

An AI-first repository begins extremely small.

repo/
├ README.md
├ AGENTS.md
└ WORKFLOW.md

These three files define everything an AI agent needs:

File	Purpose
README.md	explains the repository
AGENTS.md	defines agent behavior
WORKFLOW.md	defines the development lifecycle

The repository grows only when development requires it.

How Development Works

Every feature follows a structured lifecycle:

request
  → specification
  → tasks
  → implementation
  → testing
  → validation
  → documentation

The detailed workflow is defined in:

WORKFLOW.md

This ensures every change has a clear origin and purpose.

Example: Adding a Feature

Suppose a developer asks an AI agent:

“Add a REST API endpoint to create users.”

The repository evolves step-by-step.

Step 1 — Create a specification

specs/features/create-user.md

Example:

Feature: Create User API

Endpoint:
POST /users

Behavior:
Creates a new user with name and email.
Returns the created user object.

Step 2 — Create tasks

TASKS.yaml

Example:

tasks:
  - id: create-user-endpoint
    status: pending
    description: Implement POST /users endpoint

Step 3 — Implement code

The repository expands:

src/

Example structure:

src/
 └ interfaces/
     └ http/
         └ create-user

Step 4 — Add tests

tests/

Example:

tests/integration/create-user.test

Step 5 — Validate

The agent runs:

• tests
• lint
• type checks
• build checks

Only after validation passes is the task marked complete.

Progressive Repository Expansion

The repository intentionally starts minimal and grows over time.

Typical expansion triggers:

Trigger	Structure Introduced
First feature specification	specs/
Task tracking required	TASKS.yaml
First implementation	src/
First automated tests	tests/
Architecture decisions	ARCHITECTURE.md
Repository complexity increases	REPO_MAP.yaml

This prevents premature architecture and keeps the repository easy for AI agents to reason about.

Language-Agnostic Design

This repository structure works with any programming language.

Examples:

• JavaScript / TypeScript
• Python
• Go
• Rust
• Java
• C#
• C++
• multi-language monorepos

The system focuses on:

behavior
architecture
workflow

— not specific frameworks.

Traceability

Every non-trivial change should be traceable:

request
  → specification
  → tasks
  → implementation
  → tests
  → validation

This makes the codebase:

• easier for AI to reason about
• easier for humans to audit
• easier to maintain long-term

Intended Usage

This repository design works best for:

• AI-native software projects
• AI-assisted development environments
• multi-agent coding systems
• repositories where AI continuously develops software

Getting Started

1. Read AGENTS.md to understand agent behavior.
2. Read WORKFLOW.md to understand the development lifecycle.
3. Start implementing features using the workflow.

The first real feature will usually introduce:

specs/
TASKS.yaml

Design Principles

The repository structure follows five principles:

• minimal initial complexity
• explicit structure
• specification-driven development
• deterministic workflows
• AI-readable documentation

These principles allow AI agents to safely modify and scale the codebase.

Summary

This repository provides a foundation for AI-native software development.

It enables AI agents to:

• understand the system quickly
• implement features safely
• maintain traceable development history
• evolve repository architecture gradually