VibeCode-PlayBook

# VibeCoders Playbook

Purpose: lightweight multi-agent repo workflow for humans and LLMs.

Primary audience:
- developers onboarding to the repo
- agentic coding assistants
- LLM systems that need a compact, explicit operating model

Compatible assistants:
- Codex
- GitHub Copilot
- Claude
- other chat-based coding assistants that can follow repo instructions

Canonical docs entry:
- docs/index.html
- docs/pages/resources.html

Primary files:
- AGENTS.md: operating rules, ownership, load order, and definition of done
- agent_docs/active_context.md: current goal, scope, task, validation, next step
- agent_docs/project_brief.md: durable product context
- agent_docs/tech_stack.md: actual stack, commands, boundaries, environment
- agent_docs/verification.md: real checks and manual validation steps
- .agents/reference-links.md: objective-based external references by domain
- README.md: installation and usage guide

Required load order:
1. AGENTS.md
2. agent_docs/active_context.md
3. only the specific agent_docs/*.md files needed for the current task

Default workflow:
- prompt-engineer -> owning agent(s) -> tester -> reviewer

Escalate to security when the change involves:
- auth
- secrets
- permissions
- uploads
- risky integrations
- sensitive data flows

Escalate to legal when the change involves:
- privacy
- consent
- retention
- analytics or tracking
- AI disclosures
- policy-sensitive copy or risky claims

Escalate to devops when the change involves:
- CI/CD pipelines
- deployment strategy or safety
- environment/config parity
- infrastructure provisioning or runtime operability

Ownership:
- db: schema, migrations, queries, persistence contracts
- backend: APIs, validation, business logic, auth, backend contracts
- frontend: UI, accessibility, client behavior, frontend integration
- devops: CI/CD, deployment safety, environment, infrastructure delivery
- tester: runtime flow validation across layers
- security: trust boundaries and data exposure review
- legal: privacy and compliance risk review
- reviewer: final regression and risk review

Repo map:
- .ai/.agents/*
- scripts/install.ps1
- scripts/install.sh
- scripts/install.cmd
- .ai/.codex/*
- .ai/.claude/*
- .ai/.github/*
- agent_docs/*

Guidance:
- keep prompts compact
- do not bulk-load every document
- do not restate the whole repo in every prompt
- verify runtime behavior before calling work done
- prefer this file first when a machine-readable summary is needed
- if your assistant does not support named sub-agents, keep the same sequence as prompt labels inside one conversation

Inter-agent handoff contract (required):
- goal
- scope
- changes
- evidence
- risks
- next-owner
- done-criteria