vibe-build

Vibe Build

A complete build workflow the agent runs autonomously. The user makes product decisions; you make process decisions. Never ask the user to explain the workflow — follow it. Ask the user only about what to build, preferences, and approval at the gates.

The one rule

Product decisions = user input. Process = yours. Before asking the user anything, check whether it's a product decision. If it's not, decide it yourself and move on.

Phase 0 — Bootstrap (new projects only)

1. Identify the stack. If the project is completely undefined, ask exactly one question: "What should we build? (one sentence is enough)". Do not interview.
2. Research the stack yourself: current framework versions, recommended setup, and standard project layout, using web search and framework docs (use the project's documentation-lookup capability or websearch). Summarize the decisions in 5 lines max — do not paste research walls at the user.
3. Write AGENTS.md in the project root using the template in references/agentsmd-template.md. This is the project's constitution: every later phase reads it before structural decisions, so the user never has to re-explain conventions.
4. Install temp skills the project needs (max 5), following references/temp-skills.md. Skip skill installation entirely if the project is simple or your existing skills cover it.
5. Report the bootstrap in ≤ 15 lines, present your proposed numbered plan, and wait for approval before writing any project code.

Phase 1 — Plan

• Produce a numbered, scoped plan. Small tasks you can do in one session, explicitly deferred items for later.
• Get explicit approval. If the user edits the plan, the edits win.
• Beware interleaving: don't start building while the plan is still open.

Phase 2 — Build

• Follow test discipline when it fits the project: tests for logic, manual check for throwaway glue. Don't invent heavy test frameworks for simple builds; don't skip tests for logic a bug would hurt.
• Keep dependencies minimal. Every dependency is a liability the user inherits — prefer stdlib/zero-dep unless there's a clear payoff.
• Check AGENTS.md before every structural decision. Commit in small named steps so the work is bisectable.

Phase 3 — Verify (before claiming "done")

Run the project, then prove it works:

• UI exists → click through it in a real browser (Playwright or your agent's browser tool), check console errors, verify the main flows end-to-end.
• Web UI → audit accessibility and interaction quality (focus states, forms, dark mode, touch): use a design-guidelines review skill if available, otherwise self-check.
• Auth, secrets, payments, or user input touched → do a security pass: input validation, secret handling (never commit secrets; use env substitution), least-privilege defaults.
• Evidence before assertions: report what ran and what passed, or admit it failed and fix first.

Phase 4 — Ship

• "Deploy / push live / preview link" → deploy via the project's documented path. For Vercel-hostable projects, git-push to the linked project, fall back to vercel deploy --temporary when no login exists, and hand back the URL.
• Pull requests: concise body — what changed, why, how to test — not diff narration.
• A "done" commit means build+tests pass on the evidence you just gathered.

Phase 5 — Temp skill hygiene

Temp skills (Phase 0 step 4) are project-scoped. At project end or when a temp skill proves broadly useful, recommend promoting it to the user's shared skills directory (or deleting it). Never let temp skills mutate silently into permanent global installs.

Token thrift (all phases)

Read the smallest sufficient file range; don't re-read whole files you've already seen. Summarize a completed phase once instead of narrating each step. Prefer executing scripts and tools over pasting their contents into chat. Let skills load lazily by trigger — never dump a skill's body into the conversation.

References

• references/agentsmd-template.md — read and fill during Phase 0 step 3.
• references/temp-skills.md — read during Phase 0 step 4, before installing any temp skill.