Vibe Coding Workflow

Structured 5-phase AI-assisted development workflow (requirements → architecture → code generation → debugging → iteration). Use when the user mentions "vibe...

Security Scan

This is an instruction-only 5‑phase AI coding workflow whose requirements and runtime instructions are consistent with its stated purpose and do not request extra credentials, installs, or system access.

Purpose & Capability

Name and description match the content of SKILL.md: a structured requirements→architecture→code→debug→iterate workflow. The skill requests no binaries, env vars, or config paths that would be unrelated to that purpose.

Instruction Scope

SKILL.md confines actions to conversation, artifact creation (Markdown), architecture diagrams, and stepwise code generation; it does not instruct the agent to read local files, access environment variables, or transmit data to external endpoints beyond normal conversational output.

Install Mechanism

No install spec and no code files (instruction-only). Nothing is downloaded or written to disk by the skill itself, which minimizes installation risk.

Credentials

The skill declares no required environment variables, credentials, or config paths. The instructions likewise do not reference secrets or unrelated services.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request permanent presence or attempt to modify other skills or system-wide settings.

Assessment

This skill is an instruction-only workflow and appears coherent with its stated purpose. Before using it: (1) understand that it generates design docs and code — always review and test any generated code before running it; (2) avoid pasting secrets or credentials into the conversation or artifacts the skill produces; (3) if you expect the agent to edit files in your repo or run commands, confirm what it will change first; and (4) if you want stronger guarantees about privacy or file-system safety, prefer running the workflow in a sandboxed environment or with a human-in-the-loop to approve each change.

A structured 5-phase workflow for AI-assisted software development, from vague idea to working product.

• Phase 1 – Requirements: vague idea → structured requirements doc
• Phase 2 – Architecture: project structure, data flow, interface contracts
• Phase 3 – Code Generation: module-by-module implementation
• Phase 4 – Debugging: full error info + root cause + step-by-step fix
• Phase 5 – Iteration: new feature / optimization / refactor → re-enter correct phase

---

Global Principles

• You execute, user decides. End every Phase with a clear summary and a list of items awaiting user confirmation. Never auto-advance to the next phase.
• Context is first-class. Actively request, reference, and reuse requirements docs, architecture docs, and error logs. Never guess.
• Preserve artifacts. All key outputs (requirements, architecture, interface contracts, debug summaries) must be formatted as Markdown for the user to save.
• Tool separation. Use conversation for clarification, tech selection, and architecture discussion. Use code editing for creating/modifying files.
• If user says "just write the code": State the current Phase and any missing prerequisites in one sentence, then proceed per user's intent — never hard-block.
• Phase gate: Use each phase's completion checklist as the only criterion for moving forward.

---

Phase 1: Requirements

Goal: Turn a vague idea into a structured, actionable requirements document.

Complete Steps 1 → 2 → 3 in order. Do not merge or skip steps.

Step 1 — Clarify the Idea

Trigger: User describes an idea in 1–2 sentences without specifying audience, context, or pain points.

Ask:

• Who uses this, and in what scenario?
• What's the pain point? What's most unacceptable (slow / inaccurate / hard to use)?
• Are there reference products or similar tools?
• What does a typical usage flow look like?

Do not discuss tech stack yet. Summarize into 2–3 sentences: who + what scenario + what problem.

Done when:

• Problem scenario can be clearly stated in 2–3 sentences
• No remaining critical questions
• Tech stack not yet discussed

Step 2 — Technology Selection

Enter when: Step 1 is complete.

Collect constraints from user:

• Preferred language / framework
• Target runtime (local / server / serverless / etc.)
• Single-user or multi-user
• Maintenance expectations (one-off tool vs. long-term product)

Provide 2–3 tech options, each with: rough architecture, key dependencies, runtime model, pros/cons, and best-fit scenario.

Do not choose for the user. Explicitly say: "Please pick an option before I continue."

Done when:

• User has confirmed a specific option
• Language, runtime, and core dependencies recorded in a short text note

Step 3 — Structured Confirmation

Enter when: Tech stack is confirmed.

Auto-fill the requirements template from the conversation so far:

Field	Content
System background
Goal of this build
Users & use cases
Inputs / outputs (format + frequency)
Boundaries & constraints (including "out of scope")
Error handling approach
Acceptance criteria (testable, not subjective)

Show the filled template to the user. Ask them to correct inaccuracies and fill gaps.

Done when:

• Template confirmed by user with no major gaps
• At least 3 error scenarios listed
• Acceptance criteria are verifiable by test or clear manual steps
• User reminded to save this doc to the project

---

Phase 2: Architecture

Goal: Define project structure, module responsibilities, data flow, and interface contracts — before writing any implementation code.

Enter when: Phase 1 requirements doc is confirmed.

Outputs to produce:

1. Directory structure (down to file level)
2. One-sentence responsibility for each directory/file
3. Mermaid flowchart of data flow
4. Interface contracts between modules (function names, params, return types)
5. Weakest point in the design and why

No implementation code in this phase — interfaces and structure only.

Done when:

• Directory structure is clear with no overlapping responsibilities
• Data flow diagram provided; user reminded it can be rendered in their editor or draw.io
• All cross-module calls go through defined interfaces (no ad-hoc cross-layer calls)
• User reminded to save architecture doc to repo (e.g. docs/architecture.md)

---

Phase 3: Code Generation

Goal: Implement modules one at a time, consistent with the architecture doc.

Enter when: Phase 2 directory structure and interface contracts are confirmed.

For each module, state before generating:

• File path
• Module responsibility (copy or summarize from architecture doc)
• External interfaces this module depends on
• Interfaces this module exposes

One module per generation. Do not attempt to generate the full project at once.

Generation order:

1. Foundation (utilities, data models, storage layer)
2. Business logic
3. UI layer or external adapters

After each module: verify it can be imported and its key functions can be called.

Done when:

• All modules implemented and consistent with architecture doc
• No new modules or cross-layer calls not defined in architecture doc
• Config and constants centralized, not scattered as hardcoded values
• User reminded to commit with a message describing which modules were completed

---

Phase 4: Debugging

Goal: Solve problems collaboratively using complete information + root cause explanation + step-by-step execution.

Step 1 — Gather Full Context

Ask user to provide:

• Complete error text (start to finish)
• Exact steps taken before the error
• Expected behavior vs. actual behavior
• Already-tried solutions that didn't work

Step 2 — Explain the Error

• Describe what the error means in plain language
• List 1–3 most likely causes, ranked by priority

Step 3 — Step-by-Step Fix

• Provide clear, sequential fix steps
• Ask user to report back after each step — do not let them run all steps at once

Step 4 — Summary

After resolution, output:

Problem: ___; Cause: ___; Fix: ___

Remind user to save this note for future reuse.

If unresolved after 3+ rounds in the same conversation:

• Suggest opening a new conversation
• Paste the full error and all attempted solutions from scratch
• Explicitly request: "Analyze from a completely different angle — do not repeat previous directions"

---

Phase 5: Iteration

Goal: For each type of change, re-enter the correct phase.

Scenario	Entry point
New feature	Phase 1 (Step 1) — treat as a small project; note existing stack in "System background"
Performance / UX issue (working but slow/awkward)	Phase 4 — describe the felt problem + paste relevant code
Messy code structure (works but hard to maintain)	Phase 2 — redesign module boundaries before adding features

Done when:

• Current change type is identified
• Relevant phase artifact updated (requirements doc / architecture doc)
• User reminded to note the purpose and scope of this iteration in the commit message