# vibecoding-workflow
**An AI agent skill that enforces execution discipline in AI-assisted development.**
> The three most common ways AI agents fail you: they expand scope on their own, over-engineer for a 0→1 product, and run commands without asking. `vibecoding-workflow` makes the collaboration contract explicit.
Compatible with Claude Code, Cursor, Codex CLI, Gemini CLI, and any agent that supports SKILL.md.
---
## The Problem
When you use an AI agent to build a product, the default dynamic is broken:
- The agent "helpfully" refactors code you didn't ask it to touch
- It adds abstraction layers for hypothetical future requirements
- It changes 5 files when you asked it to change 1
- It runs `npm install` or `git push` without confirming
You end up reviewing diffs you didn't expect, reverting changes you didn't want, and losing trust in the agent's judgment.
`vibecoding-workflow` fixes this by making the agent's operating rules explicit — before the first line of code.
---
## Core Rules
### Rule 1 — Five-Section Prompting Structure
Every development task gets mentally reconstructed into five sections. If any section is missing, the agent asks before starting:
| Section | Content | If missing |
|---------|---------|------------|
| **① Scope lock** | Which files/components can be touched | Ask: "Is the scope limited to X?" |
| **② Result description** | What does success look like from the user's perspective | Ask: "What should the final result look like?" |
| **③ Off-limits list** | What must not change (tokens, routes, deps) | Default: don't touch tokens, routes, or packages |
| **④ Diff preview** | Show changes before making them | Always show diff and wait for confirmation |
| **⑤ Stop signal** | Pause after each file | Always stop after each file, don't chain changes |
**④ and ⑤ are non-negotiable defaults** — the agent does them without being asked.
### Rule 2 — Never Expand Scope
**Seeing a problem ≠ fixing the problem.** If the agent notices something outside the current task scope:
- It writes the finding to `ideas_inbox.md` (creates it if missing)
- It uses A/B/C labeling
- It continues the current task without interrupting
```
[B-Polish] 2026-05-22 src/components/Sidebar.tsx line 42 — spacing inconsistency
[C-Extend] 2026-05-22 Users might want draft-saving functionality
[A-Fix] 2026-05-22 onClick unbound in empty state — outside current task scope
```
The agent reports new inbox entries at task completion, not mid-task.
**Exception:** A-class findings that would directly break the current task can prompt: *"I found X which looks like a bug. Handle now or log to inbox?"*
### Rule 3 — Reject Over-Engineering in 0→1 Stage
> **Before adding any abstraction layer: is this 0→1 or 1→10?**
In 0→1 (pre-real-users), the agent actively pushes back on:
- State machines with more than 4 states
- Abstraction layers with only one consumer
- Config/plugin systems (no second use case yet)
- Caches, queues, event buses (no real bottleneck)
- Multi-platform frameworks (primary platform not proven yet)
**0→1 signals** (any one is enough):
- No real users yet
- Core value proposition not validated in MVP
- User journey (open → derive value) not proven end-to-end
When the agent spots over-engineering in 0→1:
> *"This design would be valuable in 1→10. For now I suggest [simplest approach]. Want me to log the full design to inbox as C-class for later?"*
---
## Task Checklist
Before starting any task, the agent runs through:
```
□ Is the scope clear? If not → ask
□ Is the success condition clear? If not → ask
□ Is there an off-limits list? If not → default to: no token changes, no route changes, no new packages
□ Is the task atomic? (One sentence summary?) If not → suggest splitting
□ Is this 0→1? If yes → watch for over-engineering
□ Does ideas_inbox.md exist? If not → create it
□ Recommend: create a new branch before starting
```
---
## During Execution
- **Before editing any file:** output a diff or change description, wait for confirmation
- **After each file:** stop and say *"[filename] done — continue?"*
- **Out-of-scope finding:** write to inbox, don't interrupt
- **Tempted to add a layer:** ask *"Is this 0→1 or 1→10?"*
- **Before running commands with side effects:** confirm *"Run [command] now?"*
---
## At Completion
1. List every changed file (diff summary)
2. If inbox has new entries, surface them for review
3. **Do not suggest next steps** — the user drives from the inbox. Let them decide what comes next.
---
## Installation
### Claude Code
```bash
curl -L https://github.com/dmlin7777777/vibecoding-workflow/raw/main/SKILL.md \
-o .claude/skills/vibecoding-workflow/SKILL.md
```
### Manual
Copy [`SKILL.md`](./SKILL.md) into your agent's skills directory.
---
## Anti-Patterns This Prevents
- **"I also cleaned up X while I was there"** — scope creep, never acceptable
- **"For future extensibility, I added an abstraction layer"** — rejected in 0→1
- **"I think this approach is better"** — agent can suggest, but cannot change without confirmation
- **Changing 5 files then reporting** — must stop after every file
- **"I rewrote the component and refactored its props"** — refactors are separate tasks
---
## Relationship to Other Skills
| Skill | Role |
|-------|------|
| **vibecoding-workflow** | Execution discipline — scope, diff preview, file-by-file confirmation |
| [ideas-inbox](https://github.com/dmlin7777777/ideas-inbox) | The inbox mechanism this skill references for out-of-scope findings |
| [build-forward](https://github.com/dmlin7777777/build-forward) | When a new idea is ready to be acted on, build-forward decides how to integrate it |
These three skills form a complete loop: **vibecoding-workflow** controls execution, **ideas-inbox** captures what's out of scope, **build-forward** handles integration when ideas graduate.
---
## License
MIT