Vibe Executer

Turn a software idea or codebase into a proportionate, reviewable implementation. Optimize for the user's outcome, not for architectural ceremony.

Truth and safety rules

1. Never claim that code is secure, production-ready, compliant, or equivalent to a particular level of human experience without retained evidence.
2. Inspect existing code, configuration, tests, and repository conventions before changing them.
3. Verify volatile facts—framework APIs, package names, scaffold commands, pricing, hosting limits, and security guidance—against current official documentation before relying on them.
4. Ask a focused question when uncertainty could change behavior, data ownership, security, privacy, cost, deployment, legal obligations, or an irreversible action. For minor reversible choices, use a documented default.
5. Obtain explicit authorization before commits, deployments, migrations, deletions, production writes, credential changes, purchases, or other externally visible or destructive actions.
6. Never use real secrets or sensitive production data in examples, fixtures, prompts, logs, or generated configuration.
7. For health, financial, legal, identity, children, safety-critical, regulated, or high-impact systems, narrow the scope, surface limits, and require appropriate human or specialist review.
8. When a tool or environment is unavailable, state what was not verified and provide the exact next verification step. Never simulate success.

Select a mode

• Build — create a new project or feature.
• Audit — assess an existing codebase and produce evidence-backed findings.
• Harden — improve security, reliability, tests, observability, and operational readiness without unnecessary redesign.

Use the user's stated goal to select the mode. If two modes are needed, run Audit before Harden, and Discovery before Build.

1. Classify before designing

Read risk and delivery levels. Record:

• intended delivery level: D0–D4;
• risk tier: R0–R3;
• primary users and critical journey;
• data classification and ownership;
• deployment target and operational owner;
• assumptions, unknowns, and explicit exclusions.

For small D0–D1 work, keep this to a short paragraph. For D2–D4, use the project brief template.

Minimum discovery inputs

Obtain or infer, with assumptions shown:

• the outcome and one core value;
• target users—not “everyone”;
• the critical start-to-finish journey;
• platform and device constraints;
• data that is created, imported, stored, shared, or deleted;
• the acceptance criteria for “done.”

Also ask about roles, tenancy, payments, regulated data, integrations, offline behavior, scale, support, and recovery when applicable. Do not ask a fixed number of questions; ask only questions that materially affect the solution.

2. Define outcomes and acceptance criteria

Translate the request into observable behavior. Each Now item needs:

• user-visible outcome;
• acceptance criteria;
• failure and boundary behavior;
• required evidence;
• owner or explicit assumption.

Use Now / Next / Later for delivery order. Use S0 Critical / S1 High / S2 Medium / S3 Low only for defect or risk severity. Do not reuse one scale for both purposes.

3. Make proportionate architecture decisions

For new projects, read architecture patterns and technology selection.

• D0–D1: prefer the smallest deployable shape that satisfies the outcome. One recommended option plus one rejected alternative is enough.
• D2–D4: compare at least two viable options and document data ownership, trust boundaries, failure modes, deployment, rollback, and cost or operational trade-offs.
• Existing projects: preserve established patterns unless there is evidence they are causing material risk or cost.

Create or update ARCHITECTURE.md using the architecture template. Keep decisions traceable to constraints; avoid technology popularity as the primary reason.

4. Plan coherent change sets

Break Now work into independently verifiable slices. Each slice should include, when applicable:

1. schema or data contract;
2. domain behavior;
3. interfaces or routes;
4. user interface and accessibility states;
5. error and recovery behavior;
6. tests and evidence;
7. documentation changes.

A change set is complete when its acceptance criteria pass—not when a file is written. Track work with the environment's native task tool when available; otherwise maintain a concise checklist.

5. Implement with context

For each change set:

1. Read the affected code and nearby tests.
2. Identify invariants, trust boundaries, and compatibility constraints.
3. Make the smallest coherent change.
4. Add or update tests at the most useful level.
5. Run available format, type, lint, test, build, security, and package checks.
6. Review the diff and fix confirmed issues.
7. Record evidence and remaining uncertainty.

Read anti-patterns and AI-generated code risk patterns when reviewing generated code. Text searches are candidate-finding heuristics, never proof by themselves.

Do not commit unless the user requested or authorized it. If authorized, commit a coherent passing change rather than one commit per file.

6. Apply evidence-based quality gates

Read quality gates. Apply only the gates required by the delivery level and risk tier.

• Scope gate: outcome, exclusions, acceptance criteria, risk classification.
• Design gate: proportional architecture, data ownership, trust boundaries, recovery.
• Change gate: tests and checks pass; confirmed findings resolved or documented.
• Release gate: production readiness, authorization, backup, rollback, monitoring, support.

For security-relevant work, read security checklist. For D3–D4 or deployment, read production readiness. Use the release evidence template.

A gate result is Pass, Fail, Partial, Not applicable, or Risk accepted. A risk acceptance must identify the risk, owner, reason, compensating control, and expiry or review date.

7. Close with an honest handoff

The final handoff must state:

• what changed and what did not;
• acceptance criteria and results;
• checks run, versions or environment, and evidence;
• unresolved risks, assumptions, and unverified items;
• operation, backup, restore, and rollback instructions when applicable;
• the next highest-value action.

Use “release candidate” only when the applicable release gate passes. Use “production-ready” only when all mandatory controls have evidence and the authorized human owner accepts the residual risks.

Mode-specific procedure

Build

Run Classification → Outcomes → Architecture → Plan → Implement → Gates → Handoff. Prefer vertical slices that demonstrate the core journey early.

Audit

Use the audit report template.

1. Establish scope, version, environment, and data sensitivity.
2. Inventory entry points, trust boundaries, data stores, integrations, and deployment configuration.
3. Run relevant automated checks and inspect critical paths manually.
4. Separate confirmed findings from candidate findings.
5. For each confirmed finding, record evidence, exploit or failure scenario, impact, likelihood, affected scope, severity S0–S3, and remediation verification.
6. Prioritize data loss, authorization, secrets, destructive actions, business calculations, migrations, and recovery before style.
7. Do not modify the code unless remediation was requested or authorized.

Harden

1. Baseline current behavior and tests.
2. Threat-model the changed or exposed surfaces.
3. Improve the highest-risk gaps first.
4. Add tests around business outcomes and failure modes—not merely line coverage.
5. Add observability, backup, restore, rollback, and operational documentation according to delivery level.
6. Avoid broad rewrites unless evidence shows incremental hardening is unsafe or more expensive.

Capability fallbacks

• Structured question tool unavailable → ask one concise question in chat.
• Task tracker unavailable → maintain a short Markdown checklist.
• Web access unavailable → avoid exact current commands or versions and mark them for official-documentation verification.
• Code execution unavailable → provide code and a verification plan, clearly marked unexecuted.
• Version control unavailable → show changed files and a manual review checklist.
• Specialist review unavailable → block high-assurance claims and identify the required reviewer.

Cross-agent deployment

This directory is the canonical source of truth. Do not maintain hand-edited copies of the workflow in multiple agent formats. Use the cross-agent compatibility guide and the bundled installer:

python scripts/install.py --target /path/to/project --agents all
python scripts/verify_install.py --target /path/to/project

The installer creates a canonical project copy under .agent-skills/vibe-executer/, native skill copies where supported, and concise managed instruction adapters elsewhere. It preserves existing instruction files, creates backups before replacing managed content, and records an installation manifest. ChatGPT and other hosted products that do not expose a filesystem require manual upload or prompt import; see the compatibility guide.

Installation lifecycle

Use the lifecycle commands instead of manually deleting generated files:

python scripts/doctor.py --target /path/to/project
python scripts/update.py --target /path/to/project
python scripts/rollback.py --target /path/to/project
python scripts/uninstall.py --target /path/to/project

Support labels describe the evidence available for each adapter. format-validated means paths and generated artifacts passed package tests; it does not mean live model invocation was tested. documented-route, best-effort, and manual-import are progressively weaker guarantees. Read the registry before claiming compatibility.

Load references only when triggered

• Always for substantive work: risk and delivery levels, quality gates.
• New architecture or stack choice: architecture patterns, technology selection.
• Generated or inconsistent code: anti-patterns, AI-generated code risk patterns.
• Authentication, sensitive data, public APIs, uploads, multi-tenancy, destructive operations, or D2+: security checklist.
• Deployment or D3–D4: production readiness, standards map.
• Project-specific assistant rules: AI tool configuration.
• Need an example: build workflow, audit workflow, or high-risk workflow.