Agent Vibe Workflow Optimizer

Stop losing 30 minutes per session to context exhaustion and off-track drift. Scaffold → Iterate → Validate → Reflect: a 4-phase framework for AI-assisted coding.

The Problem

You open Claude Code, say "build a REST API for a todo app," and the agent starts generating routes, models, and middleware in random order. By turn 15, the context has 8 open files, the build is broken (missing imports), and you don't know what's been completed. You start a new session, repeat the same setup steps, and hit the same wall. The pattern repeats: prompt → generate → hit a wall → context exhausted → start over. Without structure, each session is a fresh attempt at the same problem with no memory of what went wrong.

What You Get

• Scaffold phase — a 5-minute pre-code setup that defines iteration boundaries (one-sentence scope statement), creates agent config files (CLAUDE.md/.cursorrules), establishes the validation baseline (type-check, test, lint commands), and initializes context budget tracking at 60%
• Iterate phase — focused 10-20 minute cycles with one goal per cycle, inline assumption markers (// ASSUME: X), mid-cycle boundary checks every 5-8 tool calls, and git commit anchors after each successful cycle
• Validate phase — deterministic post-cycle checks: build gate (tsc/py_compile/go build), test gate (pytest/npm test/go test), and manual review gate for hallucinated APIs, plausible-but-wrong logic, and missing edge cases
• Reflect phase — VIBE_LOG.md entries capturing "what worked" and "what didn't" after every 3-5 cycles, with config updates that encode recurring issues as project rules
• Context budget management — hard limit at 60% context consumption: commit, scaffold fresh, continue — preventing the "almost done but context exhausted" failure mode
• Meta-learning feedback loop — reflection entries feed back into CLAUDE.md/.cursorrules as project rules, so the second session starts faster than the first

Why This Beats Prompting It Yourself

Better prompts don't fix bad workflows. Even a perfectly crafted prompt fails if the agent's context is exhausted, the scope is unbounded, or there's no validation gate between "looks right" and "actually works." This skill addresses the workflow layer — the structure around the prompts — by enforcing bounded iteration, mandatory validation after every cycle, and systematic reflection that makes each session learn from the last.

Example Session

You: I want to build a React dashboard with user auth and data visualization.

Agent: Let's scaffold first. One-sentence scope: "A working login form with JWT auth and a dashboard page showing a bar chart of user activity."

Created CLAUDE.md with tech stack (React, Express, PostgreSQL), scope statement, and "check before done" list. Installed tsc, jest, set up tsconfig.json. Context budget: 3 files open, ~15% consumed.

Cycle 1: "Implement JWT login endpoint." → Generate → tsc --noEmit passes → git commit "vibe: JWT login endpoint" Cycle 2: "Implement React login form with error handling." → Generate → npm test passes → git commit "vibe: login form" Cycle 3: "Add dashboard page with bar chart." → Generate → build passes → test fails (missing mock for chart library) → fix code → test passes → git commit "vibe: dashboard chart" Reflect: "Noticing test failures consistently catch missing mocks. Added to CLAUDE.md: 'Mock all chart library imports in test files.'"

Use Cases

• Structuring a greenfield project build where you're using an AI agent for 80%+ of the code
• Recovering from context exhaustion mid-session without losing progress
• Training an AI agent on your project conventions through the reflection → config update loop
• Running parallel iteration cycles on separate features with commit anchors for isolation
• Building a repeatable development process that scales from a weekend project to a 2-week sprint

Known Limitations

The scaffold phase adds 5 minutes of upfront time that feels unnecessary for trivial changes. For one-off code generation with no iteration needed, prompt directly without the workflow. The context budget threshold (60%) may need adjustment for models with larger context windows — the optimal percentage depends on the specific agent and project size.

Tags: vibe-coding workflow-optimization ai-assisted-development claude-code cursor rapid-prototyping

Version: 1.0.0