Vibe Coding Production Kit – a production workflow for AI coding agents

Build with AI like an engineering team — not like a chat session. Vibe Coding Production Kit (VCP) is a production-minded operating system and zero-runtime-dependency CLI for AI-assisted software development. It turns vague “vibe coding” into a repeatable engineering lifecycle built around specifications, architecture, bounded tasks, repository-native agent rules, readiness gates, security, verification evidence, independent review, safe updates, and recovery. It is model-agnostic and works with tools such as Codex, Claude Code, Cursor, GitHub Copilot, and other coding agents. Arabic documentation: README.ar.md Run the published npm package directly — no global install required: npx vibe-coding-production init . --agent all --stack auto --yes Or target another repository: npx vibe-coding-production init ./my-app --agent claude --stack auto --yes Preview without writing: npx vibe-coding-production init . --agent all --stack auto --dry-run The executable is also available as vcp when installed or invoked through npm package tooling. If you intentionally want to run the repository version instead of the published npm package: npx --yes github:MoeEyani/Vibe-Coding-Production-Kit init . --agent all --stack auto --yes The CLI requires Node.js 22+, has no runtime dependencies, and auto-detects TypeScript, Python, and Go only when repository evidence supports that decision. New here? Follow the end-to-end 10-minute Quickstart . Most vibe-coding workflows optimize for getting the first demo working. VCP optimizes for the 100th feature, the second developer, production incidents, security reviews, migrations, refactors, upgrades, and years of maintenance. | Casual vibe coding | Vibe Coding Production Kit | |---|---| | Prompt is the source of truth | Repository docs are the source of truth | | Large “build this app” requests | Small bounded task contracts | | Agent starts coding immediately | Readiness + plan-before-code gates | | “Tests should pass” | Executed verification evidence | | Same agent builds and judges | Independent review workflow | | Copy templates once | Versioned lifecycle state + safe updates | | Overwrite/reinstall to upgrade | Baselines, merge, migrations, rollback | | Hope production is okay | Security, observability, release/recovery thinking | init ↓ task ↓ ready --stage plan ↓ context --mode plan ↓ plan ↓ ready --stage implement ↓ context --mode implement ↓ implement ↓ verify ↓ independent review ↓ doctor ↓ release / observe When a newer VCP version is available: update --check ↓ update --dry-run ↓ resolve conflicts if any ↓ update ↓ doctor vcp init now creates .vcp/manifest.json and persistent baseline snapshots. Once a repository is initialized, VCP refuses to replace that lifecycle state with init --force ; upgrades go through the update engine. Check version state: vcp update . --check vcp update . --check --json Preview the full migration plan without writing project files: vcp update . --dry-run Apply after reviewing the plan: vcp update . Recover the newest safe recovery point: vcp rollback . Detach or re-track one VCP-managed file without deleting local content: vcp manage ignore AGENTS.md vcp manage track AGENTS.md The update engine uses: - persistent baseline hashes and snapshots; managed ,generated , andpreserve ownership policies;- bounded three-way merge for independent edits; - explicit CONFLICT instead of guessing on overlaps; - versioned migration declarations for renames/removals; - lifecycle locking before planning and mutation; - path traversal and symlink protections; - transaction state, backups, post-apply verification, and automatic rollback; - conservative rollback semantics instead of pretending partial historical backups are complete snapshots. See docs/UPDATES.md for the full contract and docs/CLI.md for commands/options. The read-only doctor checks whether the engineering system is actually configured—not merely copied: npx vibe-coding-production doctor . It reports concrete PASS / WARN / FAIL findings for agent instructions, unresolved verification commands, source-of-truth documents, untouched templates, CI, plan/review workflow, manifest compatibility, baseline integrity, and interrupted update transactions. Use --json for automation or --strict to make warnings non-zero. See docs/DOCTOR.md . npx vibe-coding-production task accept-invite --title "Accept invitation" The generator creates docs/tasks/accept-invite.md with source-of-truth links, acceptance criteria, scope boundaries, security/privacy questions, failure modes, observability, tests, rollout/recovery, implementation planning, review checks, and the verification commands actually configured in AGENTS.md . See docs/TASK-PACKS.md . vcp ready accept-invite --stage plan vcp ready accept-invite --stage implement The planning gate requires a real outcome, resolvable Source of Truth, concrete acceptance criteria, and explicit scope. The implementation gate additionally requires resolved architecture/data/integration boundaries, domain invariants, security/privacy, failure modes, observability, testing, rollout/recovery, and a concrete implementation plan. vcp context accept-invite --mode plan Use --mode implement , review , security , or release as the task progresses. Add only affected implementation files with repeatable --include flags. Context packs reject repository escapes and enforce a size budget by default. Preview exactly what would execute: vcp verify accept-invite Execution requires explicit consent and an implementation-ready task: vcp verify accept-invite --run \ --output .vcp/evidence/accept-invite.json Commands run sequentially and stop after the first failure. Evidence records command, status, exit code, signal, timeout state, and duration, while raw stdout/stderr is deliberately not persisted by default. See docs/VERIFICATION-EVIDENCE.md . Start with examples/reference-saas-invite/ to see the workflow as concrete engineering artifacts instead of blank templates. It models a security-sensitive multi-tenant invitation vertical slice with completed product/domain/architecture/data artifacts, ADR, threat model, test strategy, bounded task, layered code, and negative-path tests for authorization, tenant boundaries, token hashing, expiry, replay, and email binding. cd examples/reference-saas-invite npm test npm run check The example explicitly documents what remains unproven for real production infrastructure instead of calling a demo “production-ready.” Do not ask AI to build your project. Build a system that makes it difficult for AI to build your project incorrectly. The human owns intent, trade-offs, architecture, risk acceptance, and final decisions. AI helps research, plan, implement, test, review, document, and automate — inside explicit constraints. Idea -> Product brief -> PRD + acceptance criteria -> User flows -> Domain model -> Architecture + ADRs -> Data model -> Threat model -> Test strategy -> Epics / stories / bounded tasks -> Readiness gate -> Plan before code -> Bounded implementation -> Verification evidence -> Independent review -> CI gates -> Release + observability -> Safe VCP lifecycle updates -> Learn and update the source of truth AGENTS.md — repository-wide rules for coding agents.- Product templates — product brief, PRD, user flows, acceptance criteria. - Architecture templates — domain model, system design, data model, ADRs. - Security template — threat modeling before implementation. - Test strategy — unit/integration/contract/E2E decision framework. - Delivery system — Definition of Ready, Definition of Done, task/release checklists. vcp task — bounded repository-native task contracts.vcp ready — separate plan/implementation readiness gates.vcp context — bounded phase-specific AI context packs.vcp verify — explicit execution and verification evidence.vcp doctor — repository/system health audit without a misleading magic score.vcp update — lifecycle-aware safe updates with merge/migrations/recovery.- Agent prompts — discovery, planning, implementation, review, security, refactoring, release review. - GitHub hygiene — issue templates, PR template, contributing guide, security policy, validation workflow. - English README plus an Arabic guide. docs/product/PRODUCT-BRIEF.md docs/product/PRD.md docs/product/USER-FLOWS.md docs/architecture/DOMAIN.md docs/architecture/ARCHITECTURE.md docs/architecture/DATA-MODEL.md docs/security/THREAT-MODEL.md docs/testing/TEST-STRATEGY.md Then customize AGENTS.md with real repository commands for install, format, lint, typecheck, unit/integration tests, build, and E2E. flowchart LR A[Select task] --> B[Read Source of Truth] B --> C[Readiness: plan] C --> D[Build plan context] D --> E[Plan without editing] E --> F[Readiness: implement] F --> G[Implement bounded scope] G --> H[Verification evidence] H --> I[Self-review diff] I --> J[Independent review] J --> K{Quality gates pass?} K -- No --> G K -- Yes --> L[Merge / release / observe] . ├── AGENTS.md ├── README.md ├── README.ar.md ├── CONTRIBUTING.md ├── SECURITY.md ├── bin/ ├── lib/ ├── docs/ │ ├── 00-START-HERE.md │ ├── QUICKSTART.md │ ├── CLI.md │ ├── UPDATES.md │ ├── product/ │ ├── architecture/ │ ├── security/ │ ├── testing/ │ └── delivery/ ├── prompts/ ├── examples/ ├── scripts/ └── .github/ - Specs before implementation. - Architecture decisions are recorded, not buried in chat history. - No large unbounded agent tasks. - External input is validated at trust boundaries. - Authorization is server-side and resource-specific. - Schema changes use reviewed migrations and rollback thinking. - Tests are added with behavior, not postponed to the end. - The builder is not the only reviewer. - CI is the mechanical source of truth when CI is available. - Production must be observable and recoverable. - Lifecycle upgrades are planned and reversible; templates are not blindly recopied. A good agent task normally has: - one primary outcome; - a narrow set of affected modules; - explicit acceptance criteria; - known tests; - no unrelated refactor; - a diff small enough for a human to understand. If a task requires a long explanation of “and while you're there…”, split it. The kit intentionally avoids locking you into one AI vendor. Keep universal rules in AGENTS.md , and add tool-specific instruction files only when they provide real value. Do not duplicate conflicting rules across multiple agent configuration files. Prefer one source of truth and thin adapters. - CLI bootstrap with evidence-based TypeScript/Python/Go profiles - Context-aware task pack generator - Two-stage task readiness gate - Phase-specific bounded context packs - Safe verification evidence workflow - Read-only doctor audit - Worked reference vertical slice - Versioned lifecycle state and safe vcp update - Three-way merge, migrations, locking, backup, rollback, and manage ignore/track - Mobile stack profiles - Monorepo-aware stack/CI profiles - Security profiles for common application classes - Git-aware review/release automation - Prompt evaluation suite for coding agents - Architecture fitness-function examples - Extensible community profile/plugin system See CONTRIBUTING.md if you want to help. MIT — use it in personal, commercial, and open-source projects.