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 --yesOr target another repository:
npx vibe-coding-production init ./my-app --agent claude --stack auto --yesPreview without writing:
npx vibe-coding-production init . --agent all --stack auto --dry-runThe 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 --yesThe 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.
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 --jsonPreview the full migration plan without writing project files:
vcp update . --dry-runApply 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.mdThe update engine uses:
- persistent baseline hashes and snapshots;
- managed,- generated, and- preserveownership policies;
- bounded three-way merge for independent edits;
- explicit CONFLICTinstead 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 implementThe 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 planUse --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-inviteExecution requires explicit consent and an implementation-ready task:
vcp verify accept-invite --run \
--output .vcp/evidence/accept-invite.jsonCommands 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 checkThe 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 doctoraudit
- 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.