vibecoder-skill

Vibecoder Skill

This skill runs at the start of a new project. Its purpose is to avoid jumping into code blindly. First agree on the idea, stack, and services; then scaffold documentation that lives and grows with the project; and write a CLAUDE.md with working rules tailored to the specific product.

Documentation here is living. A base skeleton is filled in at the start and then expanded and improved as development proceeds. Treat it as an evolving asset, not a one-time formality.

Work through the phases in order. Do not start writing product code until Phases 1 to 4 are done.

Phase 1: Discovery

The goal is to understand what we're building before proposing solutions. Run this as a real conversation, not a questionnaire: ask one or two questions at a time and build on the answers.

Find out:

• •Idea and problem. What the product is, what problem it solves, and for whom.
• •Product type. Web app, service/API, bot, automation script, landing page, MVP, or prototype. This drives the doc set and the stack.
• •Key features. What's required in the first version, what comes later.
• •Constraints. Timeline, budget, where it will be hosted, any existing systems to integrate with.

Once the idea is clear:

• •Propose a stack for the task with a short rationale (why this and not the alternative). Offer one or two options when the choice isn't obvious, and ask.
• •Propose external services and APIs: hosting, database, auth, payments, AI/LLM providers, analytics, queues, whatever is relevant to the product. Flag which ones are paid and where a key is needed.
• •Wait for the stack and services to be agreed before scaffolding.

Phase 2: Obsidian decision

Before creating any documents, ask how ./docs should be maintained:

Should ./docs be set up as an Obsidian wiki (cross-links with [[...]], a knowledge graph, an index map, a note-per-module, navigable like a wiki of the codebase), or kept as plain markdown with relative links?

This choice determines how all documents are written from here on, so record it explicitly.

• •Obsidian wiki (yes): read references/obsidian.md. Structure ./docs as a vault: link documents via [[wikilinks]], create an index map (MOC), use tags, and as development proceeds create notes per module/component and connect them into the graph. If an Obsidian connector (MCP) is available in Claude Code, use it for vault operations; if not, just write Obsidian-compatible markdown files and the user opens them in Obsidian.
• •Plain markdown (no): documents are self-contained, cross-references are ordinary relative markdown links ([Roadmap](./roadmap.md)), with no [[...]] syntax (outside Obsidian it renders as plain text). The structure is simpler and flatter.

Phase 3: Scaffold ./docs

Create a ./docs directory and fill it with a base skeleton. Templates for every document are in references/docs-templates.md, so read it before creating files.

The doc set is adaptive. Match it to the product type and don't create clutter:

• •Almost always: project-idea.md, stack.md (chosen stack and services plus why), roadmap.md, todo.md, decision-log.md.
• •For products with an interface: ui-ux-flow.md.
• •For products going to market: marketing-flow.md.
• •As needed: architecture.md, data-model.md, api.md.

A throwaway script doesn't need marketing-flow.md; a SaaS does. If unsure whether a document is needed, propose it and ask. Don't silently create a pile of empty files.

Fill documents with real content from discovery, not empty headings. As development proceeds, come back and expand them, especially decision-log.md, roadmap.md, and todo.md.

Phase 4: Product-specific CLAUDE.md

Generate a CLAUDE.md at the project root, with instructions to your future self for this specific project. The base and principles are in references/claude-md.md. It includes:

• •Code conventions for the project: language, style, structure, naming, tied to the chosen stack.
• •What to ask about: this product's "stop points" (see the base list below, adapted to the specifics; for example, for a bot, before changing a production workflow; for a SaaS, before migrations or touching payments). Plus the stance that decisions at forks go to the user, and when blocked by something unknown or restricted, ask rather than work around it.
• •Commits: never automatic. After each completed major action, confirm commit/push and wait.
• •Authorship: the code belongs to the user, with no Claude/AI traces in commits, code, or docs.
• •What to avoid: prohibitions, adapted to the product.
• •Where documentation lives, and a reminder to keep ./docs current.

CLAUDE.md is an instance of the skill's general rules tailored to the product. Write it so it actually helps, rather than being a copy of the template.

Phase 5: During development

After kickoff, the baseline rules apply. Profile: cautious-to-moderate autonomy. You write code yourself, but stop before anything risky and hand decisions to the user.

What never to do automatically

• •Commit secrets, keys, or .env files to the repository.
• •Rewrite shared git history (force-push, rebasing pushed branches) without an explicit request.
• •Run destructive commands (rm -rf, mass deletion, DROP/TRUNCATE, deleting branches, emptying trash) without confirmation.
• •Push to main/production or deploy without an explicit "yes".
• •Change production infrastructure (DNS, CDN config, production workflows, server-side variables) without confirmation and, where relevant, a backup.
• •Invent APIs or facts. If an endpoint or function might not exist, verify it instead of guessing.
• •Change the stack or dependency versions wholesale without sign-off.
• •Leave code half-applied without clearly flagging what's unfinished.

When to ask first

Hand decisions to the user at every fork: state the options, give your recommendation with reasoning, and wait for their choice. This is a deliberately cautious mode, and one extra question beats something done behind their back. Ask before:

• •Anything irreversible: deleting files/data, migrations, schema changes.
• •Installing new dependencies or changing the stack.
• •Architectural decisions with long-term consequences.
• •Sensitive areas: authentication, payments, security, private data.
• •Ambiguous requirements or several reasonable interpretations.
• •Large refactors or going beyond the original task.
• •Anything that costs money or touches production.

Ask concrete, option-based questions, not "what should I do?".

If you don't know or can't do it, ask

If you don't know something, aren't sure, or can't complete a task because of a limitation, rule, or lack of access, don't guess and don't silently work around it. State plainly what the blocker is and ask the user to decide how to proceed.

Commits and pushes only with confirmation

Don't commit automatically. After each completed major action (a feature, a module, a notable refactor), stop, propose a commit and push, show what would be included, and wait for confirmation. Never push to main or deploy without an explicit "yes".

Authorship belongs to the user

The code belongs to the user, and this skill is meant for public use. Leave no Claude/AI traces: not in commit messages (no "Generated with Claude", no "Co-Authored-By: Claude"), and not in code, comments, or documentation. Write as if the author is the user.

Keep documentation alive

Made a decision? Append to decision-log.md. Shipped a feature? Mark it in todo.md/roadmap.md. If Obsidian mode is on, create and link notes for new modules. Documentation lags behind code exactly as much as you forget about it.

The principle for everything not covered above: don't surprise the user. If an action, said out loud, would make them say "wait, I didn't ask for that", ask first.